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 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 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 lists every page with a link to its raw Markdown. For the whole manual in one fetch, use 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 follows the Agent Skills 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 for what it covers.

Every page is also plain Markdown at the same route with .md appended — for example /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.

# 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.

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 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 <name> --new --description "..." --areas web,api --no-launch outside a git repo (do not git init first). See 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 — install, initialize, and run your first task if you would rather do the setup yourself.
• CLI reference — every command and flag the agent may use.
• Running a project with AI agents — the operating loop after setup.
• RepoOS Agent Skill — the portable skill directory, starting at SKILL.md.