# RepoOS essentials > Install RepoOS, learn the concepts, and hand setup to a coding agent. For every other page, fetch https://docs.repoos.org/llms.txt. The whole manual is https://docs.repoos.org/llms-full.txt. Current release: v0.5.77 (Nov 6, 2026) — https://github.com/repo-os/repoos/releases --- # Getting started Source: https://docs.repoos.org/getting-started.md # Getting started RepoOS runs inside a repo you already have. It doesn't host your code, and it doesn't ask you to move your work anywhere — it adds a few directories and a local server that reads them. ## Install Choose one: ### curl — preferred ```bash curl -fsSL https://repoos.org/install | bash ``` ::: tip Why curl * **Easiest to update and uninstall** — `repoos upgrade` and `repoos uninstall`, no package manager involved. * **Only method with release channels** — `repoos upgrade --channel beta|rc|canary`. ::: ### Homebrew ```bash brew install repo-os/tap/repoos ``` ### npm ```bash npm install -g @repo-os/repoos ``` ### Bun ```bash bun add -g @repo-os/repoos ``` Bun's installer puts `bun` in `~/.bun/bin`. A new shell does not see it until that directory is on `PATH`: ```bash export PATH="$HOME/.bun/bin:$PATH" ``` ### pnpm ```bash pnpm add -g @repo-os/repoos ``` On a clean Linux account pnpm has no global bin directory yet (`ERR_PNPM_NO_GLOBAL_BIN_DIR`). `pnpm setup` also fails with `ERR_PNPM_UNKNOWN_SHELL` when `SHELL` is unset (common in non-interactive scripts). Set a shell, run setup, then open a new terminal so `PNPM_HOME` is on `PATH`: ```bash export SHELL="${SHELL:-$(command -v bash)}" pnpm setup ``` mise is not a recommended install method. Its npm backend refuses packages under a weekly-downloads threshold unless low-download installs are allowed, and that path still waits out mise's minimum release age, so you get the previous version. `mise unuse --global` leaves a broken shim until `mise prune`. The curl installer puts the release in `~/.local/share/repoos` and a `repoos` launcher in `~/.local/bin`. Machine state (running servers, service registry, check slots) stays in `~/.repoos`. `repoos uninstall` removes the install, the launcher it created, and those state entries, and it prints anything else it left in `~/.repoos`. It does not delete per-repo files. Pipe the installer to `bash` (`curl … | bash`). ## Updating RepoOS Update with the same tool you used to install it. Do not run `repoos upgrade` for a package-manager install: it leaves that install alone and prints the matching command when it can identify the source. | Installed with | Update command | | --- | --- | | curl | `repoos upgrade` | | Homebrew | `brew update && brew upgrade repo-os/tap/repoos` | | npm | `npm update -g @repo-os/repoos` | | Bun | `bun update -g @repo-os/repoos` | | pnpm | `pnpm update -g @repo-os/repoos` | `repoos upgrade --channel beta`, `--channel canary`, and `--channel rc` are available only for the curl install. Package-manager installs follow their package manager's stable release channel. RepoOS runs on **Bun** when it's available and falls back to **Node.js 20.6.0 or newer** otherwise — see [Configuration → Worktrees and runtime](/configuration#worktrees-and-runtime) if you want to pin one. ## Initialize a repo From the root of any git repo: ```bash repoos init ``` Fresh installs keep RepoOS metadata under `repoos/` by default; the interactive prompt can instead use the repo root or another location. Init does not overwrite an existing file. With the default layout it creates: | Path | What it is | | --- | --- | | `repoos.toml` | Configuration. Every field is optional. Always at the repo root. | | `repoos/work/` | One markdown file per task. This is the board. Includes `0001-set-up-repoos.md` (a `done` example) and an inbox starter task. | | `repoos/docs/` | Context an agent needs to work on *this* project — architecture notes, decisions, history. | | `AGENTS.md` | Instructions agents read first. The cross-tool standard; Claude Code, Codex, Cursor, Aider and Zed all read it. Always at the repo root. | | `.env.example` | Names of secrets a fuller setup expects. No values. | | `.gitignore` | Created, or appended when one already exists. Ignores the derived cache, root `.repoos/` runtime state, `.env`, `.env*.local`, `node_modules/`, task and input attachment directories, and `.DS_Store`. | | `repoos/.repoos/canary.txt` | Tracked canary counter. | A new project also runs `git init` and, unless you pass `--no-commit`, commits the scaffold (`chore: initialize RepoOS project`). Init in an existing repo does not make that commit. Run `repoos init` outside a git repo and it starts a guided flow for a brand new project instead. In a terminal it asks a few questions; with no TTY (an agent, a script) pass `--new` and answer them with flags: ```bash repoos init myproject --new \ --description "A tiny social app for book clubs" \ --areas web,api --no-launch ``` See the [CLI reference](/cli#repoos-init-name) for every flag. Don't `git init` first to avoid the prompts — that routes you to the existing-codebase starter instead of the new-project one. Either way the board is never empty: init seeds a starter task. Which starter depends on what's in the repo — if there are no meaningful source files yet (a fresh `git init`, a README-only repo, or only RepoOS's own scaffold) it seeds "Flesh out the product vision and initial architecture"; once there is code to read it seeds "Read this codebase and propose project docs + an initial task backlog". The one-line summary after init says which was chosen and why. Force one with `repoos init --starter vision|codebase`. In an interactive terminal, `repoos init` also asks whether you want to install coding agents. If you opt in, it shows detected agents, lets you select missing ones, and asks before running each agent's install command. Install failures leave the manual command on screen and do not stop initialization. Init never signs you in; it lists sign-in guidance for installed agents that still need authentication. This step is skipped in non-interactive and CI runs. Global `npm i -g` installs can require a writable npm prefix or elevated permissions such as `sudo`, depending on your npm setup. The starter is seeded as an **`inbox`** task, not `ready` — it's a suggestion for you, not work to auto-run, and `created_by` is `repoos-init` so it can be filtered (and archived) once a real backlog exists. Promote it when you want it picked up: ```bash repoos mv 0002 ready ``` Both starters are self-contained enough to work without an agent — read the task, do what it says, and it turns into project-context docs and concrete follow-up tasks. (`repoos/work/0001-set-up-repoos.md` is still scaffolded, but it's marked `done`: it's a worked example of a task file, not work to do.) ## Starting a new project as an agent An AI agent starting a brand-new RepoOS project hits a fork the interactive docs don't cover: the new-project flow asks questions on a terminal, and an agent's shell usually has no terminal. This section is the recipe that works today, and the traps to avoid. ::: warning Use the new-project flow, not `git init` first The guided flow is what seeds the **new-project** starter task. If you run `git init` first and then `repoos init`, `repoos init` only sees "an existing git repo" and seeds the **existing-codebase** starter instead (`read-the-codebase`) — the wrong first task for a project with no code yet. Starting RepoOS outside a git repo is what selects the right starter. ::: ### Non-interactive flags (the supported path) Use a non-interactive `repoos init` that takes the project name, description, and areas as flags, so an agent never needs a terminal at all: ```bash repoos init my-project --new \ --description "A tiny demo project" \ --areas web,api \ --no-launch ``` `--new` runs the guided flow with answers from flags and sensible defaults (commit the scaffold; never launch the console unless `--launch`). See the [CLI reference](/cli#repoos-init-name) for every flag — `--description-file -` reads a multi-line description from stdin, `--layout` picks the repo-root or `repoos/` layout, and `--json` prints a machine-readable summary. Without `--new` and without a TTY, the command refuses and prints the exact `--new` command to run, plus the `git init` warning below. ### Pseudo-terminal fallback (legacy workaround) Before `--new` existed, the only way to drive the flow without a terminal was a real pty. Prefer the flags above; this is kept for older releases. `pty.fork()` hands the process a terminal, then you answer the prompts on its file descriptor: `repoos init` in a non-git directory, with no TTY on stdin/stdout, refuses: ``` This directory isn't a git repo, so repoos init needs interactive prompts. Run it in a terminal, or run `git init` first and then `repoos init` again. ``` The second line is the trap above, not the fix. The fix is to give the process a real terminal. `pty.fork()` hands it one, then you answer the prompts on its file descriptor. ~15 lines, Python 3, no dependencies: ```python import pty, os, sys, time script = "\n".join([ "my-project", # project name (Enter = current directory) "", # layout: Enter = repoos/ subdir "y", # git init + scaffold? [Y/n] "A tiny demo project", # one-line project description "", # task areas to seed (Enter = skip) "", # preview-target stubs? [Y/n] "", # starter check plan? (if offered) "n", # commit the scaffold? [Y/n] "n", # launch the web console? [Y/n] ]) pid, fd = pty.fork() if pid == 0: os.execvp("repoos", ["repoos", "init"]) # the child gets the TTY else: for answer in script.split("\n"): while True: data = os.read(fd, 1024) if not data: break sys.stdout.buffer.write(data); sys.stdout.buffer.flush() if data.rstrip().endswith((b":", b"]")): # a prompt is waiting os.write(fd, (answer + "\n").encode()) break os.waitpid(pid, 0) ``` Run it from the directory that should hold the project. It produces the same files an interactive run would, including the correct `flesh-out-the-vision` starter. The exact prompts shift between releases, so treat the answers list as a starting point and adjust from the output. ### Right after init 1. **Read `AGENTS.md`.** It's the operating loop for this repo — where the board is, how to create tasks, how to hand off. Everything below is in more detail there. 2. **The starter task is a suggestion, not a queue item.** Init leaves `flesh-out-the-vision` in `inbox`. It is not dispatched until someone promotes it (`repoos mv 0002 ready`); don't auto-run it. 3. **Never hand-edit `work/*.md`.** Create and change tasks with `repoos new`, `repoos mv`, `repoos update`, `repoos note`, or the HTTP API — never by editing frontmatter or files directly. 4. **Start the server in a real terminal tab, or as a service.** An agent shell reaps background processes when its command returns, so a `repoos serve` started with `&` from a tool call dies with it. Either run it in a terminal you keep open, or register it as a managed background service: ```bash repoos service install # register a managed background service repoos service start # it survives the shell that started it repoos service status ``` Never run `repoos serve` from inside a short-lived agent command and expect it to stay up. ## Give the project docs Project docs under `repoos/docs/` are the context an agent reads before it starts. RepoOS never invents them and never imposes a structure, but it can bring your own or scaffold a starting point — both are opt-in. Import an existing doc set (a directory, a single file, or a `.zip`): ```bash repoos init --docs-from ~/Downloads/project-docs # or, in an already-initialized repo: repoos docs import ~/Downloads/project-docs.zip ``` The import preserves the folder structure, ignores macOS junk, refuses to overwrite an existing file unless you pass `--force`, and prints what it copied. Add `--dry-run` to see the plan without writing anything. During the guided `repoos init` flow you can instead paste a path at the "Import existing docs from a folder?" prompt. If you don't have docs yet, ask for the starter skeleton: ```bash repoos docs scaffold ``` That writes an index `README.md` with a reading order, plus short `product.md`, `architecture.md`, `conventions.md` and `glossary.md` stubs, each with prompts for what to put there. Nothing is created unless you run that command (or answer yes to the scaffold prompt in the guided flow). `repoos doctor` warns if `AGENTS.md` never points at the docs index, if docs exist that the index doesn't link, or if the docs directory is empty while tasks exist. ## Start the server ```bash repoos serve ``` Check which agents are enabled before you run this. Serve starts the local control plane — a web UI and an API over the same files — 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 in `repoos.toml`. A project with no `[[agents]]` rows uses the built-in defaults, which leave 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. Set `watchdog.enabled = false` to stop that. It picks a stable port derived from the repo's path, so two different repos never collide; pin one with `servePort` if you'd rather. Stop it with `repoos stop`. The UI is where you'll spend most of your time: the board, agent chats, task diffs, and the review controls all live there. ## Create your first task Either from the UI, or: ```bash repoos new "Fix the login redirect loop" ``` Tasks start in `inbox`, including the starter `repoos init` seeds. Move one to `ready` when it's specified well enough to hand over: ```bash repoos mv 0002 ready ``` (`0001` is the `done` scaffolding example; your seeded starter is `0002`.) ::: warning Let RepoOS write task files Never hand-edit task files. Status, activity history and metadata are written through the CLI and API so the board stays consistent — use `repoos mv`, `repoos update`, and `repoos note` rather than editing frontmatter directly. ::: ## Let an agent work it Assign the task to an agent from the UI. RepoOS creates a dedicated git worktree and branch for it, runs the coding agent there, and streams its output live. Your primary checkout is never touched. When the agent is finished it asks for the task to move to `review` and stops. RepoOS re-runs the check, commits the branch and does the moving — the task stays `active` with a *running checks* badge until that finishes. The agent does **not** merge its own work. Review the diff, then move the task to `done`, which is what actually merges the branch to your trunk. A new project gets built-in reviewer, engineer, pm and CTO prompts seeded on first start, so the roles work without any setup. They carry the review lessons RepoOS learned driving itself: report the whole class of a bug in one pass, read earlier review reports, separate code defects from evidence gaps, check the branch still merges with its base, and flag a task for a human after repeated review passes. Project-specific rules belong in `AGENTS.md` and your own `[[agents]]` text; RepoOS never overwrites them. See [Configuration → Agents](/configuration#agents) to customize a role or adopt a newer default. ## The bar for "done" ```bash repoos check ``` One command is the whole definition of done: build, tests, and whatever else your repo declares (see [Checks before merge](/check) for the full list and what's opt-in). Agents must get this green before handing a task back to you, and it runs again before anything merges. ## Where to go next * [CLI reference](/cli) — every command. * [Configuration](/configuration) — `repoos.toml` and environment variables. * [Concepts](/concepts) — how tasks, worktrees and the lifecycle fit together. * [Running a project with AI agents](/running-with-agents) — a practical loop for driving a board with agents. Starting this repo with an AI agent? See [Starting a new project as an agent](#starting-a-new-project-as-an-agent) above for the recipe and the traps. --- # Concepts Source: https://docs.repoos.org/concepts.md # Concepts ## The repo is the source of truth A task is a markdown file in your configured task directory (`repoos/work/` on a fresh install). Its status is a field in that file's YAML frontmatter. Tasks are markdown files — there is no separate board database behind the UI. RepoOS may create gitignored runtime files under `.repoos/` (for example `repoos.db` when login is enabled); those are not the task board. The UI is a view over the task files, and anything derived (the index, caches) can be deleted and rebuilt. This has practical consequences you'll feel immediately: * Tasks are versioned, diffable and reviewable like code. * Task history travels with a clone. Nothing lives in a service you can lose access to. * An agent can read the board with `cat`, and your project's context is sitting right next to the code it describes. ## Git history in the UI The Context page (`/repo`) includes a **History** tab: the repository's `git log`, grouped by day, with branch and path filters. Commits that follow the `type(NNNN):` message convention (for example `docs(0514): …`) link to that task. Opening a commit shows the files it changed and a full diff — the same diff view used for task worktrees. The log is read-only. Checkout, revert, and cherry-pick stay on the command line. The left sidebar also shows a small **canary** digit (0–9) above the git summary. Clicking it starts a deliberately trivial task that walks the full lifecycle (draft through done) by incrementing the digit in `.repoos/canary.txt` in your repo — a smoke test that any failure is in the pipeline, not your product code. The digit reflects that file on disk and advances after a canary run merges. The git row below it is a one-line summary of the checkout you are actually running from: the branch, and `clean`, `dirty (n)` or `unknown`. It describes the **repo root checkout only** — task worktrees are separate, and a task branch moving never flips it. A warning colour means either the checkout is not on the base branch (or HEAD is detached) or there are uncommitted changes; `unknown` is what you see when git could not be read or the last check is older than a minute and a half, and it never means clean. The ℹ button next to it opens the detail: the changed files with their status letters when dirty, the three most recent commits exactly as the History tab lists them (`docs(NNNN):` bookkeeping excluded), how long ago the state was checked, and a link into History. It reads the same data as the History tab and is read-only — committing and switching branches stay on the command line. The state is pushed to every open tab over the event stream when it changes (working-tree writes, branch switches, commits, staging, and RepoOS's own task-file commits), with focus, tab-visibility, reconnect and a slow interval as backstops. One cadence note: git's own state changes are pushed immediately, but an ordinary edit outside the task tree (say, under `src/`) is not watched — watching the whole checkout would be a lot of filesystem noise for one indicator. Those edits show up on the next backstop (window focus, tab visibility, event-stream reconnect, or the 45-second interval), so the row can be up to ~45 seconds behind an edit made with a plain text editor. Staging or committing that edit pushes it at once. ## Status is a field, not a folder ```yaml --- id: "0001" title: Fix the login redirect loop status: ready priority: p1 --- ``` Tasks move through `inbox → ready → active → review → done` by editing that one field in place. Files never move between directories, so a status change is a one-line diff instead of a rename, and two people moving different tasks never conflict. ::: warning Don't hand-edit task files Status, activity log and metadata are written by RepoOS so the board stays consistent. Use `repoos mv`, `repoos update`, `repoos note`, or the UI. ::: ## What each status means | Status | Meaning | | --- | --- | | `inbox` | Captured, not yet specified well enough to act on. | | `ready` | Specified. An agent (or person) can pick this up as-is. | | `active` | Being worked, in its own git worktree. | | `review` | Implementation finished and checks pass. Waiting on a human. | | `done` | Approved and merged. | ## Pipeline view The Work Queue page has two views, switched with the **Pipeline | Board** toggle in the header. **Board** is the default and shows every status. **Pipeline** is a horizontal race track for the work in flight: one lane per task in `active` or `review`, plus recently merged tasks. Your last choice is remembered. Lanes run through six stage columns, left to right: **Coding**, **Checks**, **Handoff**, **Review**, **Close-out**, **Merged**. Each card sits in the column of its current stage and moves backwards too — when review sends a task back, it returns to Coding with a small amber "sent back" note on its lane. `ready` tasks are not lanes; a **Ready · n** count sits at the left edge. The **Merged** column is the tinted goal: recently merged tasks sit in it for ten minutes, then drop off the track. Stuck, needs-input, paused and held are states, not stages: the card stays where it stalled, with a red (stuck), amber (needs input) or green (merged) chip, and held/paused cards render dimmed. Each card shows four lines: id, type and priority; the title; the live step ("Coding", "Running checks 3/5", "Confirming handoff", "In review", "Merging") with time in this state; and the engineer round (`E2`), reviewer round (`R1 ✓`), model(s) and run host (`this Mac` or the remote host name). Click a card to open the task panel, exactly like a board card. The small icon button (pause, resume, or a check mark once merged) acts without opening the panel and is reachable by keyboard. ## Archiving a task Archive parks a task you don't intend to finish right now **without changing its status**. A task archived from `review` is still `review` underneath — it just stops appearing in the board columns, and unarchiving drops it back into that same column. Nothing else changes: the branch and worktree are kept, so an archived task resumes exactly where it left off. Use **Archive task** at the bottom of the task panel and optionally give a reason. Archiving is refused while a run, review, or close-out is still live, because hiding a half-stopped run from the automatic scanners would orphan it — stop the work first. A running preview is not a refusal: archiving stops it (the recorded preview process and its build shell) as part of parking the task. Archived tasks live in a minimised **Archived (n)** list below the board on the Work Queue page. Archiving is orthogonal to status: there is no `archived` status, and it never merges, stops, or deletes anything. From the CLI, `repoos list` hides archived tasks by default and prints a count; `repoos list archived` shows them, and `repoos show ` marks an archived task. `repoos mv` refuses to move an archived task's status — unarchive it first (from the Archived list, or `POST /api/tasks/:id/unarchive`). An archived task that another task `depends_on` does **not** count as done: the dependent stays blocked and reads *“Blocked by archived task #id; unarchive it to unblock”* until the upstream is unarchived. ## Stories A **story** is an optional grouping over tasks: a delivery slice that spans several areas and owners, tagged with a matching `story:` value and optionally described by a markdown file under `stories/`. Forms the shared background for a related set of tasks — why the work exists, decisions already made, the tasks it contains — without repeating it in every task body. A story has no worktree, branch or status of its own; it is complete when all its tasks are done. See [Configuration → Stories](/configuration#stories). Agents get this background too: when a tagged task with a registered story is picked up, the engineer and the reviewer both receive the story's title, the path to its definition file, the sibling tasks (ids, titles, statuses) and a bounded excerpt of the definition in their prompt. So the context you write once into a story steers the work, not just the humans reading the board. ## One task, one worktree When a task goes active, RepoOS creates a dedicated git worktree and branch for it. The agent works there — never in your primary checkout — so you can keep working while an agent does, and several tasks can be in flight without stepping on each other. ## Checks before merge ```bash repoos check ``` This is the single bar for "did this break anything?". It runs the check plan your repo declares in `repoos.toml` — the same command for Go, Gradle/Android, Rust, JavaScript or a mix — and each step ends in a pass, a failure, a timeout, a missing-prerequisite error, or an explicitly-stated skip (see [Checks before merge](/check)). An agent must get it green before handing work back, and it runs again before anything merges. Because it's one command with a non-zero exit code on failure, the same checks works locally, in CI, and inside RepoOS's own close-out pipeline. ## Humans hold the merge Human-assigned tasks follow a separate, inert board pathway. They can move between Inbox, Ready, Active, Review and Done without starting AI work or running checks, review or close-out. The drawer identifies them as human work and offers **Mark done** with an optional completion note. `hold` is not required for a human-assigned task. AI agents may change its board status only when the human explicitly asks them to. An agent that finishes a task asks for it to move to `review` and **stops**. It does not merge its own branch, and it can't — the merge happens only when a human moves the task to `done`. Reaching `review` is a request, not a status edit: RepoOS commits the branch, runs `repoos check` and passes a commit guard first, from whichever route you use (the **Review** button, a board drag, `repoos mv`, or the agent). Until that finishes the task is still `active`. See [Review and close-out](/review-and-close-out). If a reviewer agent is enabled, it reads the branch diff and writes an advisory report for that review — findings, edge cases, suggestions. It changes nothing and it doesn't replace your approval; it's there to make your review faster. ## Your docs directory is the project's memory `repoos init` creates `repoos/docs/` alongside `repoos/work/` by default. It holds the context an agent needs to work on *your* project: architecture notes, decisions and their rationale, incident write-ups, conventions that aren't obvious from the code. This matters more than it sounds. An agent starting a task reads `AGENTS.md` and your configured docs directory to get oriented — so knowledge you write down once stops being re-derived, re-litigated, or re-broken on every future task. ::: tip Your docs directory is for building *your* project. The documentation you're reading now — how to use RepoOS itself — is a separate thing, kept in its own directory in the RepoOS repo. ::: ## AGENTS.md `AGENTS.md` is the cross-tool standard for agent instructions, read directly by Claude Code, Codex, Cursor, Aider, Zed and others. `repoos init` scaffolds one describing the task lifecycle and the rules of your repo. Add a one-line shim only if a tool you use ignores it. --- # Adding RepoOS to an existing repo Source: https://docs.repoos.org/existing-repo.md # Adding RepoOS to an existing repo RepoOS is designed to drop into a repo you already have. `repoos init` is idempotent — it **never overwrites an existing file**, only creates what's missing — so it's safe to run on an established project. ## What `repoos init` adds From the root of your repo: ```bash repoos init ``` By default, RepoOS files live under a `repoos/` subdirectory to keep metadata out of your project source. You can choose a different location or explicitly pick the repo root during the interactive prompt. It creates only what isn't already there. With the default layout: | Path | What it is | | --- | --- | | `repoos.toml` | Configuration. Every field is optional. Always at the repo root. | | `repoos/work/` | One markdown file per task. This is the board. Includes `0001-set-up-repoos.md` (a `done` example) and an inbox starter task. | | `repoos/docs/` | Context an agent needs to work on *this* project — architecture notes, decisions, history. | | `AGENTS.md` | Instructions agents read first. The cross-tool standard; Claude Code, Codex, Cursor, Aider and Zed all read it. Always at the repo root. | | `.env.example` | Names of secrets a fuller setup expects. No values. | | `.gitignore` | Created, or appended when one already exists. Ignores the derived cache, root `.repoos/` runtime state, `.env`, `.env*.local`, `node_modules/`, task and input attachment directories, and `.DS_Store`. | | `repoos/.repoos/canary.txt` | Tracked canary counter. | On an existing repo the inbox starter is `0002-read-the-codebase.md` (read this codebase and propose `repoos/docs/` plus an initial backlog). Promote it with `repoos mv 0002 ready` when you want it picked up. A brand-new project seeds `0002-flesh-out-the-vision.md` instead, runs `git init`, and unless you pass `--no-commit` commits the scaffold (`chore: initialize RepoOS project`). Init in an existing repo does not make that commit. With the default layout, `repoos.toml` persists the configured paths: ```toml workDir = "repoos/work" docsDir = "repoos/docs" skillsDir = "repoos/skills" storiesDir = "repoos/stories" inputsDir = "repoos/inputs" cacheDir = "repoos/.repoos" ``` If `.gitignore` already exists, it is only *appended* to for the RepoOS ignore lines that are missing. An existing `AGENTS.md` is never overwritten: in an interactive terminal, `repoos init` previews a small RepoOS guidance section and adds it only if you explicitly approve it. Non-interactive runs leave it unchanged. Re-running `repoos init` reports "already set up" and changes nothing else. ## Choosing a layout During interactive `repoos init`, you'll be prompted: ``` Where should RepoOS files live? [repoos/] ``` * **Enter** accepts the default `repoos/` subdirectory. * Type a custom path like `.meta/repoos/` to nest it elsewhere. * Type `/` to place `work/`, `docs/`, and `.repoos/` at the repo root (the original layout). `repoos.toml` and `AGENTS.md` always stay at the repo root regardless of the layout choice. ## Defining your areas In an interactive terminal, `repoos init` also offers to seed the task-area vocabulary that powers the drawer's area picker and the PM prompt: ``` Task areas to seed the area picker — comma-separated (e.g. web, cli, api; Enter to skip): ``` Type names (or press Enter to skip) and RepoOS appends real `[[areas]]` rows to your existing `repoos.toml`. If you give areas, it then asks whether to scaffold commented `[[preview.targets]]` stubs for them, since preview targets route by area and the two are usually set up together. Both prompts are skippable, and a repo that already declares any `[[areas]]` is never asked again. You can edit the list later in **Settings → General → Areas** or by hand — see [Configuration](/configuration#areas). ## What it doesn't touch Your source, your `package.json`, your build pipeline, and your existing docs are all untouched. RepoOS adds a few directories and a local server that reads them; it isn't a hosted service and it doesn't ask you to move your work anywhere. If your project uses a build pipeline RepoOS doesn't recognise, the [checks](/check) degrade gracefully rather than failing you for not looking like RepoOS. ## Adopt incrementally You don't have to move your whole roadmap at once: 1. Run `repoos init` and commit the scaffolded files. `AGENTS.md` is what agents read first, so getting it into the repo is what makes agents useful here. 2. Add a handful of tasks with `repoos new` and work them through the lifecycle. 3. Grow `repoos/docs/` as you go — each durable decision you write down once stops being re-derived on every future task. See [Concepts](/concepts). ## Running it outside a git repo Run `repoos init` in a directory that isn't inside a git repo and it switches to a guided flow for a brand-new project instead: it can create the project in a subdirectory, offer a repo-root or `repoos/`-subfolder layout, take a one-line description, and optionally make the initial commit. That description is embedded in the starter task ("Flesh out the product vision and initial architecture"), so the first thing on the board is turning it into a real vision, architecture notes and a follow-on backlog. ::: tip Starting a brand-new project with an agent? Don't `git init` first — that makes `repoos init` see an existing repo and seed the wrong starter. See [Starting a new project as an agent](/getting-started#starting-a-new-project-as-an-agent) for the non-interactive recipe and pitfalls. ::: ## Next ```bash repoos serve # local control plane, plus background agents — check first repoos new "Fix the login redirect loop" ``` Before `repoos serve`, check which agents are enabled. Serve starts the web UI and API, 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. Then see [Install and first task](/getting-started) for the lifecycle, or [Configuration](/configuration) for `repoos.toml`. --- # Using RepoOS with an AI coding agent Source: https://docs.repoos.org/ai-agents.md # Using RepoOS with an AI coding agent If you already work with a coding agent, you don't have to install RepoOS by hand. Point the agent at this page and give it the starter prompt below. It reads a short overview first, checks your repository, and asks before it changes anything. Claude Code, Codex, OpenCode, and Cursor are common examples — nothing here depends on which agent you use. This page covers setup. Once RepoOS is installed and initialized, [Running a project with AI agents](/running-with-agents) covers the operating loop: planning tasks, choosing models, review, and close-out. ## How the agent reads RepoOS The public material is built for progressive disclosure, so an agent can start small and fetch more only when it needs it: * **A short overview first.** [repoos.org/llms.txt](https://repoos.org/llms.txt) explains what RepoOS is, who it is for, and the verified install commands. * **The docs index next, only if needed.** [docs.repoos.org/llms.txt](/llms.txt) lists every page with a link to its raw Markdown. For the whole manual in one fetch, use [llms-full.txt](/llms-full.txt). * **One starter prompt.** The text below is the only copy. Every surface that offers to copy it reads the same canonical file, so there is no second version to drift. * **One portable skill.** The [RepoOS Agent Skill](https://github.com/repo-os/repoos/tree/main/agent/skill) follows the [Agent Skills specification](https://agentskills.io/specification). Install that one directory under your agent's own skills location, for example `~/.claude/skills/repoos/`. RepoOS publishes no provider-specific plugin, branded integration, or per-vendor copy. See the [skill page](/agent-skill) for what it covers. Every page is also plain Markdown at the same route with `.md` appended — for example [`/getting-started.md`](https://docs.repoos.org/getting-started.md) — so an agent can fetch the source instead of the rendered HTML. ## The starter prompt Copy this into your agent. It tells the agent what to read, what to inspect, and when to ask. ```md # 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 --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. ``` ## What to expect * The agent reports whether RepoOS is already installed (`command -v repoos`) and whether this repository is already initialized (`repoos.toml`). * If RepoOS is missing, it picks a method from [Install](/getting-started#install) that fits the machine — curl is the default (it needs Bun or Node.js 20.6.0+), and Homebrew, npm, Bun, and pnpm are also supported — and asks before running a global install. mise is not a recommended method. * It runs `repoos init` only after you agree. An existing repo uses `repoos init` from the repository root. A new project uses `repoos init --new --description "..." --areas web,api --no-launch` outside a git repo (do not `git init` first). See [Initialize a repo](/getting-started#initialize-a-repo) for the files that creates and for what `repoos serve` starts. * It explains what changed, and asks before any significant edit outside the RepoOS scaffold. ## Permission guidance Tell the agent these three rules before it starts; the starter prompt repeats them so they survive a fresh session: * **Inspect the repository first.** Run `git status`, `git remote -v`, and `git log -1 --oneline` before installing or editing anything. Read what is already there instead of assuming an empty project. * **Preserve existing files and Git changes.** Do not reset, clean, stash, or commit someone else's work. `repoos init` never overwrites an existing file: it creates only what is missing. * **Ask before significant edits.** A global install, a change outside the RepoOS scaffold, or anything that rewrites project files needs your explicit agreement first. ## Keep going * [Getting started](/getting-started) — install, initialize, and run your first task if you would rather do the setup yourself. * [CLI reference](/cli) — every command and flag the agent may use. * [Running a project with AI agents](/running-with-agents) — the operating loop after setup. * [RepoOS Agent Skill](https://github.com/repo-os/repoos/tree/main/agent/skill) — the portable skill directory, starting at `SKILL.md`. --- # RepoOS Agent Skill Source: https://docs.repoos.org/agent-skill.md # RepoOS Agent Skill RepoOS publishes one portable [Agent Skill](https://github.com/repo-os/repoos/tree/main/agent/skill) for coding agents that do not run inside RepoOS. It follows the [Agent Skills specification](https://agentskills.io/specification): `SKILL.md` is short, deeper workflows live in `references/`, and its commands and flags match the installed CLI. Fetch the directory, or just the raw [`SKILL.md`](https://raw.githubusercontent.com/repo-os/repoos/main/agent/skill/SKILL.md). Claude Code, Cursor, Codex, and similar agents install that one directory under their own skills location (for example `~/.claude/skills/repoos/`); RepoOS does not keep provider-specific copies. The skill covers what RepoOS does, how to detect an existing install, the supported install commands, `repoos init` and the default `repoos/` layout, where tasks and project docs live, how to discover commands, how to create tasks and stories, and how to leave unrelated Git changes alone. For the install and init walkthrough, see [Getting started](/getting-started); for every command and flag, see the [CLI reference](/cli).