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

# 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-duragit). Older repos use `.duragit/`: for each of `kb/` and `architecture/`, the folder under `.rebasely/` is the one that counts when it exists, else the one under `.duragit/`. The paths below say `.rebasely/`; read `.duragit/` instead where that is what the repo has. Before you plan a change:

- Read `.rebasely/kb/index.md`, then the concepts, decisions and guides it links with `[[id]]` that touch your task. Decisions in `.rebasely/kb/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 and `repo:write` to merge. If a command answers 403, say so and stop; do not look for another credential.

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