---
url: 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`.