# RepoOS

> Your AI dev team, living in your repo, for CTOs and builders. RepoOS keeps a project's task board in the repository itself: tasks are Markdown files, coding agents work them in isolated Git worktrees, and a person reviews and approves every merge. It is for a small team or an independent developer using a coding agent such as Claude Code, Codex, OpenCode, or Cursor.

Current release: v0.5.77 (Nov 6, 2026) — https://github.com/repo-os/repoos/releases/tag/v0.5.77

RepoOS is local-first and source-available. The package has no runtime npm dependencies. It runs on Bun, with Node.js 20.6.0 or newer as a fallback.

## How it works

- Tasks are Markdown files with their status in YAML frontmatter, versioned by Git.
- Each task gets its own branch and Git worktree, and agents work there — never in your main checkout.
- Checks run before handoff, and a person approves the merge. Agents never merge their own work.

## Install

Choose one. curl is the default (Bun, or Node.js 20.6.0+); the package managers below install the same CLI.

```bash
curl -fsSL https://repoos.org/install | bash
brew install repo-os/tap/repoos
npm install -g @repo-os/repoos
bun add -g @repo-os/repoos
pnpm add -g @repo-os/repoos
```

## Start

```bash
repoos init    # scaffold repoos/work/, repoos/docs/, and AGENTS.md by default
repoos serve   # start the board; prints the local URL to open
```

## Documentation

- [Documentation index](https://docs.repoos.org/llms.txt): Every user-manual page as a raw Markdown link, with a one-line description.
- [Essentials bundle](https://docs.repoos.org/llms-essentials.txt): Install, concepts, and agent setup in one file, small enough for one fetch.
- [Full manual](https://docs.repoos.org/llms-full.txt): The whole user manual concatenated.
- [Getting started](https://docs.repoos.org/getting-started.md): Install RepoOS, initialize a repository, and open the board.
- [CLI reference](https://docs.repoos.org/cli.md): Every command and flag, including tasks, stories, and worktrees.
- [Using RepoOS with an AI coding agent](https://docs.repoos.org/ai-agents.md): Hand the setup to an agent, with permission guidance and the starter prompt.
- [RepoOS Agent Skill](https://raw.githubusercontent.com/repo-os/repoos/main/agent/skill/SKILL.md): The portable Agent Skill as raw Markdown — start here, then fetch the references it names.
- [GitHub repository](https://github.com/repo-os/repoos): Source, releases, and issues.

## Starter prompt

This is the canonical prompt for an outside coding agent. Copy it as-is; it is not tailored per provider.

```text
# Get started with RepoOS

Help me set up RepoOS for a new project or an existing repo.

Before you change anything:

1. Read https://repoos.org/llms.txt. It is the short overview: what RepoOS is, who it is for, and the verified install commands.
2. Inspect this repository before installing or editing anything. Run `git status`, `git remote -v`, and `git log -1 --oneline`. Check whether RepoOS is already installed (`command -v repoos`) and whether the repository is already initialized (`AGENTS.md`, `repoos/work/`, `repoos/docs/`, or `repoos.toml`).
3. Only if that overview is not enough, read the docs index at https://docs.repoos.org/llms.txt and follow only the pages you need.

Then:

- Tell the owner what you found, including whether RepoOS is already installed or initialized.
- If RepoOS is not installed, choose the install method that fits this machine: curl is the default (it needs Bun or Node.js 20.6.0+), and Homebrew, npm, Bun, and pnpm are also supported. Do not use mise. Ask before running a global install.
- Before editing, preserve existing files and uncommitted Git changes. Do not reset, clean, or commit someone else's work.
- Run `repoos init` only after the owner agrees.
  - Existing repo, from the repository root: `repoos init`
  - New project, outside a git repo (do not run `git init` first): `repoos init <name> --new --description "..." --areas web,api --no-launch`

- With the default `repoos/` layout, init creates `repoos.toml`, `repoos/work/` (including `0001-set-up-repoos.md` and an inbox starter task), `repoos/docs/`, `AGENTS.md`, `.env.example`, `.gitignore` (created, or appended when one already exists), and `repoos/.repoos/canary.txt`. A new project also runs `git init` and, unless you pass `--no-commit`, commits the scaffold (`chore: initialize RepoOS project`). Init does not overwrite an existing file. An existing repo is not committed for you.
- Before `repoos serve`, check which agents are enabled in `repoos.toml` (a project with no `[[agents]]` rows uses the built-in defaults). Serve starts the local server and background automation. The CTO board monitor ticks every 5 minutes (`ctoMonitorIntervalMs`, default 300000). When the `cto` agent has `enabled = true`, that tick launches a coding agent. Turn it off with `enabled = false` on that `[[agents]]` row. The built-in default leaves the CTO disabled. The reviewer is on by default and starts when a task enters `review`. The watchdog (`watchdog.enabled`, default true) can restart a stalled engineer.
- Explain what changed, and ask before any significant edit outside the RepoOS scaffold.

Do not invent files, commands, or flags. If something is not in the RepoOS overview, the docs, or `repoos --help`, say so rather than guessing.
```