---
name: rebasely
description: Work in a Rebasely repository the way Rebasely expects agents to. Use for any change you will push to a Rebasely remote (rebasely.com, staging.rebasely.com, their older duragit.com names, or a self-hosted Rebasely): one sandbox branch and one git worktree per task, push early, merge through Rebasely, clean up. Also for creating repositories and for asking an owner to approve what only an owner may do (making a repository public, creating an agent).
---

# Working in a Rebasely repo

Rebasely gives each task its own sandbox branch (`refs/sandbox/<owner>/<name>`): a ref that costs nothing to create, is hidden from everyone's branch list, and expires after 24 hours without pushes. Use one per task, in its own `git worktree`, so agents working in parallel never share a checkout.

## Read the repo's context first

Many Rebasely repos keep their context in `.rebasely/` (https://rebasely.com/docs/dot-rebasely): notes in `.rebasely/knowledge/` and the system map in `.rebasely/architecture/`. Older repos use `.rebasely/kb/` or `.duragit/kb/` for the notes and `.duragit/architecture/` for the map: the newest folder that exists is the one that counts (`.rebasely/knowledge`, then `.rebasely/kb`, then `.duragit/kb`). The paths below say `.rebasely/knowledge/`; read the older folder instead where that is what the repo has, and write new notes where the existing ones are. Before you plan a change:

- Read `.rebasely/knowledge/index.md`, then the concepts, decisions and guides it links with `[[id]]` that touch your task. Decisions in `.rebasely/knowledge/decisions/` are numbered and append-only; a superseded one names its replacement in `superseded-by:`. Follow the accepted ones.
- Read `.rebasely/architecture/system.yaml` (components, the paths each one owns, what each talks to) and any `views/*.yaml` for the part you will change, and the `flows/*.yaml` dataflows that run through it (ordered steps between components).
- Over MCP the same is one call each: `kb.list`, `kb.read` (with resolved links and backlinks), `kb.search` and `arch.get` (a component, or a view). In a checkout, read the files.

## Credentials

- Use your own agent token (`dga_...`), never your owner's personal token. Put it in `REBASELY_TOKEN` (older setups use `DURAGIT_TOKEN`, which still works) or git's credential helper for the host; never in a URL, a file you commit, or a log.
- Your token needs `sandbox:write` for sandboxes, `repo:write` to merge and `repo:create` to create repositories. If a command answers 403, say so and stop; do not look for another credential.

## New repositories, and what only an owner may do

- Create a repository when your task needs one: `rebasely repo create <org>/<name> --description "..." --readme` (or MCP `repo.create`, or `POST /api/v1/orgs/<org>/repos`). It is always private. Your token needs `repo:create`; an agent's new repository is added to its own token. On 403 `missing_scope`, ask the person to grant it; do not look for another credential.
- Never try to make a repository public, create an agent or change anything else an owner decides by another route. Ask for an approval instead: `rebasely repo visibility <org>/<name> public`, `rebasely agent create --org <org> --name <name> --scopes ... --repos ...`, or MCP `repo.visibility` and `agent.request`. The answer has a code: tell the person "open https://rebasely.com/approve and enter <code>" (the host's own `/approve` on staging or self-hosted), and say exactly what you asked for and why. An owner approves it with a passkey within 10 minutes.
- Follow the request with `approval.status` (MCP) or `rebasely approval wait <id>`. An approved agent's token is handed out once, to the token that asked: run `rebasely approval wait <id>` (or let `rebasely agent create` wait), which stores it in the system keychain. Never print it, paste it into chat, or commit it.
- Denied or expired means stop and ask the person; do not start the same request again and again.

## Start a task

```sh
rebasely sandbox create --from main --name fix-login --worktree ../fix-login
cd ../fix-login
```

That creates `refs/sandbox/a-<you>/fix-login` from `main`, fetches it and adds a worktree on a local branch `sandbox/fix-login`. Without the CLI:

```sh
curl -fsS -X POST -H "Authorization: Bearer $REBASELY_TOKEN" -H "content-type: application/json" \
  -d '{"from":"main","name":"fix-login"}' https://rebasely.com/api/v1/repos/<org>/<repo>/sandboxes
git fetch origin refs/sandbox/a-<you>/fix-login
git worktree add -b sandbox/fix-login ../fix-login FETCH_HEAD
```

## While you work

- Commit small and push early, after each step that builds: `git push origin HEAD:refs/sandbox/a-<you>/fix-login`. A push keeps the sandbox alive another 24 hours and lets others see your progress (`git fetch origin refs/sandbox/a-<you>/fix-login`).
- Force-pushing your own sandbox is fine; it is scratch space. You cannot push to anyone else's.
- Fetch before you start a step that depends on others' work: `git fetch origin main`, then rebase or merge locally.
- Run checks on the sandbox before merging: `rebasely sandbox checks fix-login --wait` starts the workflows that declare `on: sandbox` and exits 1 if one fails. Sandbox runs get no secrets.
- Files several agents edit at once: use live mode for them once your repo has live branches (`rebasely mount`, MCP `live.*` tools); until then keep such edits in one task.
- When you change behavior, update the knowledge base in the same sandbox: edit the concept that `describes:` the code you changed (and bump its `reviewed:` date), add a guide for a new workflow, and add a new numbered decision for a new design choice (never rewrite an accepted one; supersede it with `status: superseded` and `superseded-by:`). When you add, move or connect code, update `system.yaml`, and the flows whose steps your change adds, removes or reroutes. Then run `rebasely kb check` and `rebasely arch check` and fix what they report.

## Finish

```sh
rebasely sandbox merge fix-login --into main --mode squash
cd - && git worktree remove ../fix-login && git branch -D sandbox/fix-login
```

- `--mode ff` (the default) only fast-forwards and needs `main` not to have moved; `squash` and `merge` write one commit and report conflicts with paths and line ranges instead of writing anything. On a conflict: `git fetch origin main`, merge it into your worktree, push, merge again.
- Protected branches with required checks only take a fast-forward whose tip passed them.
- If you drop the task: `rebasely sandbox delete fix-login`, then remove the worktree.
- Before you stop, `rebasely sandbox list --mine` should show nothing you abandoned, and `git worktree list` nothing left behind.

## When the work needs a review: a pull request

When people should review your change (the repo's KB or its owners say so, or the base branch requires approvals), open a pull request from your sandbox instead of merging it yourself (https://rebasely.com/docs/pull-requests):

```sh
rebasely pr create --head refs/sandbox/a-<you>/fix-login --title "Fix the login redirect" \
  --body "What changed, why, and how you checked it." [--draft] [--reviewer <email>]
```

- Over MCP: `pr.create`, `pr.list`, then `pr.get` for what blocks the merge (checks, approvals, conflicts) and the reviews and inline threads, `pr.diff` for the changes, `pr.architecture` for what it changes in the architecture and knowledge base, `pr.comment` (with `path`, `line` and `side` for a line, `in_reply_to` for a thread) and `pr.review`. From a terminal: `rebasely pr list|view|checkout|comment|review|merge`.
- Pass the head you judged: `commit_id` to `pr.review` and `expect_head` to `pr.merge` (the `head_sha` of the `pr.get` you read; `--expect <sha>` on the CLI). If someone pushed since, the server refuses instead of applying your review or merge to code you did not read.
- You open pull requests only from your own sandboxes (or branches your token may push), and you edit or close only your own. Runs of a pull request you wrote or pushed to start without secrets until a person approves them.
- Address review comments with new pushes to the same sandbox; the pull request follows its head. Answer each thread, and let the reviewer resolve it.
- Your approvals never count toward a branch's required approvals, and you cannot approve your own pull request. Request changes or comment instead. (Nobody's approval counts on a pull request they pushed to.)
- Merge (`rebasely pr merge <n> --method squash`, or `pr.merge`) only when `pr.get` says it is ready and your task allows you to; otherwise leave it for a person.
- A pull request keeps the sandbox's commits after the sandbox ends; merging with `--delete-branch` ends the sandbox for you.
