agentleFS
notactuallytreyanastasionotactuallytreyanastasio/deciduous/docs/llms-full.txt

deciduous

llms.txt171 starsChanged 23 days agoApache-2.0View on GitHub

Deciduous records why the code is the way it is: what was asked, the approaches considered, the one chosen and what it beat, what was changed, and what happened. The graph lives on a server your team runs. Every developer's CLI and every coding agent writes to it, so the next session, yours or someone else's agent, reads the reasoning instead of guessing it from the diff. One token per server, not per person or per workspace. Anyone holding it…

  • Reads credentials
  • Installs packages
  • Sends data out
  • Commits and pushes

The file

Show its rules and text

We split this llms-full.txt into the rules it gives an agent

26 rules. About 0 are common, 11 are distinctive, and 15 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈11

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 15

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    If which -a lists two different paths, the first one runs.

    line 87
  2. Very specific:

    If setup fails with cannot reach <url>: ...

    line 144
  3. Very specific:

    If you ran init first,: before remote setup, it has no server to check and asks where the graph lives.

    line 161
  4. Distinctive:

    If the agent's nodes never show up on the server, it is writing somewhere else: go back to step 5.

    line 303
  5. Distinctive:

    Use the bundle from the same release as the CLI your team runs:

    line 339
  6. Distinctive:

    Check the install from the VM:

    line 387
  7. Very specific:

    Keep the final handle if nothing else is served on that domain.

    line 420
  8. Very specific:

    If your provider runs PostgreSQL for you, start only the server container and point it at that database.

    line 450
  9. Very specific:

    After any of these changes, restart Claude Code.

    line 599
  10. Very specific:

    Keep the mcp-session-id header from the initialize response and send it on every later request.

    line 734
  11. Distinctive:

    Run these from the repository root and read the results before doing anything else:

    line 788
  12. Distinctive:

    Before any setup command, ask:

    line 805
  13. Distinctive:

    If the user says they have no server and want one, point them at Run a server.

    line 815
  14. Very specific:

    Use init --opencode, --windsurf or --both if the user runs those assistants (Clients).

    line 839
  15. Distinctive:

    Do not change the registration yourself.

    line 854
  16. Very specific:

    Do not write a probe node such as "connection checked": it is your process, not a project decision, and with no parent it is an orphan …

    line 894
  17. Very specific:

    Commits: After a commit, log the action or outcome with commit set to the hash.

    line 913
  18. Very specific:

    Put the user's exact words in prompt.

    line 963
  19. Distinctive:

    Keep credentials out of prompts.

    line 992
  20. Very specific:

    Do not send add_node and an add_edge that needs its id in the same batch.

    line 1070
  21. Distinctive:

    When an approach is abandoned, do not edit the old decision into the new one.

    line 1171
  22. Distinctive:

    Call it before a burst of writes and after each milestone.

    line 1276
  23. Very specific:

    When one agent's node changes another's plan, record the borrow as an edge, not just a sentence.

    line 1331
  24. Very specific:

    Only a reply (--reply-to <id> or reply_to) from the addressed label takes it off that label's list.

    line 1494
  25. Very specific:

    Keep latest_id and pass it as --since next time to get only what is new.

    line 1536
  26. Distinctive:

    Start each agent from its worktree root with its label:

    line 1542

≈ “Common” is an estimate: at least 1 in 5 of the 3,727 llms.txt files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
llms-full.txt
<!-- https://deciduous.dev/content/index.md -->

# One decision graph for every agent on the team

Deciduous records why the code is the way it is: what was asked, the approaches considered, the one chosen and what it beat, what was changed, and what happened. The graph lives on a server your team runs. Every developer's CLI and every coding agent writes to it, so the next session, yours or someone else's agent, reads the reasoning instead of guessing it from the diff.

## What runs where

```
 Claude Code, OpenCode, any MCP client          deciduous CLI
   (agents, one per worktree/branch)        (add, link, remote status,
                │                              pull, watch)
                │ HTTPS, bearer token                 │ HTTPS, same token
                │ <base>/mcp                          │ <base>/ops, /export, ...
                ▼                                     ▼
        ┌──────────────────────────────────────────────────┐
        │  deciduous server (deciduous-mcp, Elixir)        │
        │  one workspace per repository                    │
        └──────────────────────────────────────────────────┘
                                │
                                ▼
                     PostgreSQL (the graph)
```

- **The server** is PostgreSQL plus the deciduous server, normally on a VM behind a TLS proxy. It exposes authenticated MCP over HTTP at `<base>/mcp`, and `/health` and `/ready` for monitoring. One server holds many repositories, each in its own workspace.
- **Agents** connect to `<base>/mcp` with a bearer token. On connect the server sends them its logging instructions, so an agent knows when to write a goal, an option, a decision, an action and an outcome without a prompt telling it.
- **The CLI** (`deciduous`) writes to the same server. A project whose `.deciduous/config.toml` has a `[remote]` table sends every `deciduous add` and `deciduous link` to the server before the command exits. The SQLite file in `.deciduous/` is this machine's cache of the server, not a second graph. `deciduous serve` shows that cache, so run `deciduous remote pull` first to see what agents wrote.

## What every session shares

- **The graph.** Goals, the options considered, the decision and what it beat, actions and outcomes, from every agent and every person, on every branch. A new session reads it before it writes: what is open on this branch, and what was already tried. [Recover context](recovery.md).
- **The message board.** Agents working at the same time ask each other questions and announce interface changes with `@label`, and each one asks what is waiting for it. [The message board](board.md).
- **Who is writing where.** `check_activity` lists the sessions that wrote in the last five minutes and the latest node on each branch, and `deciduous remote watch` prints every write as it lands. [Many agents, one graph](teams.md).

One token per server, not per person or per workspace. Anyone holding it can read and write every workspace on that server. Run separate servers for groups that must not see each other's graphs. [Architecture](architecture.md) covers the trust boundary in full.

## Where to go next

- **Your team already has a server:** [Quickstart](quickstart.md). From install to your first node, with your agent writing to the same workspace.
- **You are the one who runs it:** [Run a server](run-a-server.md), a VM with the Docker bundle and a TLS proxy, or the server binary against a managed PostgreSQL.
- **You are an AI agent told to set up or use deciduous:** [For agents](for-agents.md).
- **A client other than Claude Code, or a per-project registration:** [Clients](clients.md).
- **No server, one machine, or offline:** [Local](local.md) covers a server on your own laptop and the git-only mode where the graph is a file in the repository. Both work; neither is how a team shares a graph.

Once connected: [the workflow](workflow.md) for how a piece of work becomes nodes, [teams](teams.md) for many agents on one workspace, [the message board](board.md) for how they talk to each other, and [recovery](recovery.md) for picking up where the last session stopped.

---

<!-- https://deciduous.dev/content/quickstart.md -->

# Join your team's graph server

You need two things from whoever runs the server: its base URL and its token. With those, five commands connect a repository: `remote login` stores the token, `remote setup --url` points the repository at the server, `init` installs the agent integration, and `claude mcp get deciduous` confirms your agent talks to the same server as your CLI. Then `deciduous remote status` says In sync.

Everything below was run against deciduous 1.1.0. The examples use `https://deciduous.example.com` for the server and a repository called `my-app`; the output is real, captured against a test server, with the URL and home directory swapped in. This page does not cover running a server. For that, see [Run a server](run-a-server.md).

## The short version

```sh
brew install notactuallytreyanastasio/tap/deciduous
pbpaste | deciduous remote login --url https://deciduous.example.com   # the token, from your clipboard
cd my-app
deciduous remote setup --url https://deciduous.example.com
deciduous init
claude mcp get deciduous | grep -E 'Status|URL'   # URL must be https://deciduous.example.com/mcp
deciduous remote status                            # In sync
```

Each line is a step below, with its output and what goes wrong at it. The two that catch people: `init` run before `remote setup` offers to install a server on your machine (step 4), and Claude Code can stay pointed at a different server without anything saying so (step 5).

## 1. Install the CLI

```sh
brew install notactuallytreyanastasio/tap/deciduous   # macOS, Linux
cargo install deciduous --locked                      # Rust 1.89 or newer
```

Or download a binary from the [v1.1.0 release](https://github.com/notactuallytreyanastasio/deciduous/releases/tag/v1.1.0): `deciduous-darwin-arm64`, `-darwin-amd64`, `-linux-arm64`, `-linux-amd64`, `deciduous-windows-amd64.exe`, and `checksums.txt` to check them against.

```sh
$ which -a deciduous
/opt/homebrew/bin/deciduous
$ deciduous --version
deciduous 1.1.0
```

If `which -a` lists two different paths, the first one runs. Remove the stale one rather than installing a third. The same path listed twice, as above, is a directory that appears twice in `PATH`, not a second install; delete nothing.

## 2. Get the token

Ask the person who runs the server. They read it from the server's settings file: the value of the `DECIDUOUS_MCP_TOKEN` line, without the single quotes `setup.sh` puts around it (a token pasted with its quotes gets a 401): `.env` in the extracted Docker bundle, or `~/.config/deciduous/server/.env` for a server the CLI installed. It should reach you through your team's secret manager, not chat.

Store it with `remote login`. It reads one line from stdin, so the token stays out of shell history and the process list, and checks it against the server before writing anything. Pipe it in from wherever you keep it (`pbpaste`, your secret manager's CLI); if you paste it at the prompt instead, the terminal shows it as you paste.

```sh
$ pbpaste | deciduous remote login --url https://deciduous.example.com
Token (read from stdin, not saved to shell history): Token: stored in /Users/you/.config/deciduous/credentials
  mode 0600, outside every repository
```

A wrong token stores nothing:

```
Error: reached https://deciduous.example.com but the server rejected the token (401). Check DECIDUOUS_MCP_TOKEN.

Nothing was stored.
```

(The message names `DECIDUOUS_MCP_TOKEN` even when the token came from stdin.)

**One token per machine.** The credentials file holds a single token, not one per URL. Logging in to a second server replaces the first server's token, and every repository on this machine then sends the new one. If you work against two servers, set `DECIDUOUS_MCP_TOKEN` in the environment for one of them; the CLI reads that variable before the file.

## 3. Point the repository at the server

Make the repository's first commit before you write anything. `remote setup` itself works in a repository with no commit, but the server ties a workspace to the repository's root commit, so that an unrelated project that happens to share the directory name cannot write into your graph. In a repository with no commit, CLI writes are kept in `.deciduous/remote-log.jsonl` and `deciduous remote push` sends them after the first commit.

```sh
$ cd my-app
$ deciduous remote setup --url https://deciduous.example.com
deciduous remote setup
Every project writes its decision graph to a shared server. This connects /Users/you/code/my-app
to one: a server on this machine, or one someone else runs.

   Wrote .deciduous/config.toml [remote] url = https://deciduous.example.com
   Connected https://deciduous.example.com holds 0 nodes, 0 edges in workspace my-app
   Unchanged Claude Code already has a deciduous MCP server

Done: this project writes to https://deciduous.example.com. Restart Claude Code so it picks up the server;
it sends the logging instructions when it connects.
```

It writes this to `.deciduous/config.toml`, and nothing secret:

```toml
[remote]
url = "https://deciduous.example.com"
workspace = "my-app"
```

The workspace is the repository directory's name, lowercased (a repository in `MyApp/` gets `myapp`; a linked worktree uses its main checkout's name). Every clone and worktree of the repository should use the same one, so commit this file. To choose a different name, run `deciduous remote init https://deciduous.example.com --workspace <name>` first. `remote init` only writes `[remote]` and claims the workspace; it does not register Claude Code. Then run `remote setup --url` as above: it keeps that workspace and does the Claude Code registration. `remote setup` has no `--workspace` flag.

Without a stored token it stops before writing anything: ``Error: no token: set DECIDUOUS_MCP_TOKEN or run `deciduous remote login --url https://deciduous.example.com` first``. A token given only through `DECIDUOUS_MCP_TOKEN` works for setup but is not stored by it.

If setup fails with `cannot reach <url>: ... timed out reading response`, the server's `/health` took longer than the CLI's 15 seconds. Run it again; if it keeps happening, tell whoever runs the server.

## 4. Install the agent integration

```sh
$ deciduous init
...
   Creating .claude/commands/decision.md
   ...
   Creating CLAUDE.md
...
Shared graph server
   Connected https://deciduous.example.com holds 0 nodes, 0 edges in workspace my-app
```

`init` writes the Claude Code integration (`CLAUDE.md`, `.claude/commands/`, `.claude/skills/`, `.claude/settings.json` with an update check and a message-board hook) and then checks the server named in `[remote]`. Use `--opencode`, `--windsurf` or `--both` for other assistants; see [Clients](clients.md).

**If you ran `init` first,** before `remote setup`, it has no server to check and asks where the graph lives. In a terminal the menu is:

```
Where should this project's graph live?

  1) This machine: the deciduous server as a background service, using PostgreSQL on
     localhost:5432 as you (answering now)
  2) This machine: the server as a background service, using a PostgreSQL you name
     (any host, port, user, password)
  3) This machine, in Docker: a new PostgreSQL and the server in containers
  4) A server someone else runs: you need its URL and token

  1 and 2 install the release's server executable in /Users/you/.config/deciduous/server
  and start it at login. --docker runs that server in Docker instead.

Choose 1-4 [1]:
```

Type 4 to join your team's server; it asks for the URL, then whether to use the token already stored on this machine (step 2), or for the token if none is stored.

> **Do not just press Enter.** The default is 1: it downloads the server executable, creates and migrates a `deciduous` database on localhost:5432, and installs a background service on your machine, which is not what someone joining a team wants. Pressing Ctrl-D at the menu picks 1 as well.

The choices are the same as these flags: 1 is `remote setup --local`, 2 is `--database-url <url>`, 3 is `--docker-postgres`, 4 is `--url <url>`. If this machine already has a server installed, the menu shows two choices instead: 1) that server, 2) a server someone else runs. Piping input into `init` does not answer the menu: without a terminal it stops and lists the flags, below.

On Linux, 1.1.0's systemd unit for choices 1 and 2 does not even start: systemd rejects its quoted `WorkingDirectory=`. The fix is [#330](https://github.com/notactuallytreyanastasio/deciduous/pull/330), not yet merged or released; until then use choice 3 or run the server by hand.

Without a terminal (a script, CI, an agent's shell), `init` writes its files and then stops:

```
Error: /Users/you/code/my-app has no server configured ([remote] in .deciduous/config.toml), and there is no terminal to ask where its graph should live. Choose one:

    deciduous remote setup --local                  # this machine: a background service, PostgreSQL on localhost:5432
    deciduous remote setup --database-url <url>     # this machine's server, a PostgreSQL you name
    deciduous remote setup --docker-postgres        # this machine: PostgreSQL and the server in Docker
    deciduous remote setup --url <url>              # a server someone else runs

then rerun this command. Tests and CI in a throwaway directory can set DECIDUOUS_NO_SERVER=1.
```

It exits 1. Run step 3, then `init` again; files that already exist are skipped.

`init` 1.1.0 also sets up the no-server git mode even when `[remote]` is there: `.deciduous/graph.json`, a `!.deciduous/graph.json` line in `.gitignore` that tracks it, a `.gitattributes` line and a git merge driver. With a server, the graph is on the server and `graph.json` is only a local copy that the CLI rewrites on every write; committed, it would conflict between every two developers for nothing. Delete the `!.deciduous/graph.json` line from `.gitignore` and leave `.gitattributes` out of your commits. (`deciduous update` knows this and skips those files in a project with `[remote]`; `init` does not, and running `init` again puts the line back.)

## 5. Make sure Claude Code talks to the same server

`remote setup` registers the server with Claude Code (user scope, every repository) only when Claude Code has no server called `deciduous` yet. If it already has one, setup prints `Unchanged Claude Code already has a deciduous MCP server` and leaves it alone.

> **It leaves it alone even when that one points at a different server.** Your CLI writes then go to one graph and your agent's to another, and nothing warns you. Setup's last line still says to restart Claude Code so it picks up the server; restarting picks up the old registration.

Check it:

```sh
$ claude mcp get deciduous
deciduous:
  Scope: User config (available in all your projects)
  Status: ✔ Connected
  Type: http
  URL: https://old-server.example.com/deciduous-mcp/mcp
  Headers:
    Authorization: Bearer <token>

To remove this server, run: claude mcp remove deciduous -s user
```

Where this page shows `<token>`, the real output prints the whole token. To check without putting it on screen, `claude mcp get deciduous | grep -E 'Status|URL'`.

This is the mismatch the step exists for, and it happened while this page was being written: the project pointed at one server and Claude Code at another. The `URL` must be your `[remote] url` followed by `/mcp`. If it is not, replace the registration:

```sh
claude mcp remove deciduous -s user
claude mcp add --scope user --transport http deciduous https://deciduous.example.com/mcp \
  --header "Authorization: Bearer $(cat ~/.config/deciduous/credentials)"
```

`$(cat ...)` reads the token `remote login` stored in step 2; the shell substitutes it when the command runs, and Claude Code stores it in `~/.claude.json`, outside every repository. Do not write `$DECIDUOUS_MCP_TOKEN` here unless you exported that variable: `remote login` does not set it, and with it empty `claude mcp add` still succeeds, registers `Authorization: Bearer` with no token, and `claude mcp get` then reports `✘ Failed to connect ... (HTTP 401)`. A user-scope registration serves every repository on the machine; each tool call names its workspace. To pin one repository to its workspace instead, use a project `.mcp.json` ([Clients](clients.md#claude-code)).

Restart Claude Code after any change. The tools appear as `mcp__deciduous__add_node` and so on.

## 6. Write the first node

```sh
$ deciduous add goal "Add rate limiting to the public API" -c 90 \
    -p "Add rate limiting to the public API: 100 requests a minute per token"
Created node 1 (type: goal, title: Add rate limiting to the public API) [confidence: 90%] [prompt: 68 chars] [branch: main]

$ deciduous remote status
Remote: https://deciduous.example.com
Workspace: my-app
Log: 0 write(s) waiting, 0 rejected  (/Users/you/code/my-app/.deciduous/remote-log.jsonl)

                 local    server
  nodes              1         1
  edges              0         0

In sync: no writes waiting, and every node, edge and document matches field by field.
Themes and tags are not sent to the server, so they are not compared.
```

The goal reached the server before `add` returned. `remote status` exits 0 when in sync and 1 when anything differs. (The CLI also printed a warning that a 68-character prompt looks like a summary. Goals carry the user's message verbatim.)

## 7. Your agent writes to the same workspace

Open Claude Code in the repository. On connect the server sends the agent its logging instructions: a goal for each request, options when there is more than one way, a decision naming what it beat, actions and outcomes. Ask it to look at the rate-limiting goal and suggest approaches. It finds the goal with `query_nodes` and writes options under it with `add_node`, passing `workspace: "my-app"` and the current branch.

Your local copy is now behind, and `remote status` says exactly how:

```
                 local    server
  nodes              1         2
  edges              0         1

Only on the server (1)
  option cad0b58d "Token bucket per API token in Redis"

Edges only on the server (1)
  b1710c03 -> cad0b58d (leads_to)

Differs: `deciduous remote pull` takes the server's side.
```

```sh
$ deciduous remote pull
Pulled: my-app <- https://deciduous.example.com
  fetched 2 nodes, 1 edges, 0 deletion(s)
  imported 1 new node(s), updated 0, removed 0; imported 1 edge(s), removed 0

$ deciduous nodes
2 nodes:
ID    CHANGE    TYPE         STATUS     TITLE
------------------------------------------------------------------------------
1     b1710c03  goal         pending    Add rate limiting to the public API
2     cad0b58d  option       pending    Token bucket per API token in Redis
```

To see writes as they land, from your agent or anyone else's, keep `remote watch` open in another terminal:

```sh
$ deciduous remote watch
Watching: my-app
13:37:13  main      option      "Fixed window counter in Postgres"
```

If the agent's nodes never show up on the server, it is writing somewhere else: go back to step 5.

## 8. Commit

```sh
git add .deciduous/config.toml .gitignore CLAUDE.md .claude/
git commit -m "chore: connect to the team's deciduous server"
```

With the `graph.json` line gone from `.gitignore` (step 4), CLI writes no longer change `git status`: the SQLite cache and `graph.json` are both ignored. What stays in `git status` is what `init` wrote and you chose not to commit: `?? .gitattributes` and, unless you committed it, `?? .github/`. Delete them if you do not want them listed.

`init` also wrote `.github/workflows/cleanup-decision-graphs.yml`, which deletes the graph images `deciduous dot --auto` puts in PRs; commit it only if you use that. Stage files by name, never `git add -A`.

A teammate who clones the repository runs steps 1 and 2, then `deciduous remote setup --url https://deciduous.example.com`: it keeps the workspace in the committed `[remote]` and registers Claude Code if nothing called `deciduous` is registered yet. (Skipping it leaves Claude Code with no registration at all, and `claude mcp get deciduous` prints `No MCP server named "deciduous"`.) Then step 5, then `deciduous remote pull` to fill their local copy. The committed integration files mean they do not need `init`.

Next: [the workflow](workflow.md) for how a piece of work becomes goal, options, decision, actions and outcomes, and [teams](teams.md) for several agents on one workspace, who talk to each other on [the message board](board.md). When something here does not match what you see, [troubleshooting](troubleshooting.md).

---

<!-- https://deciduous.dev/content/run-a-server.md -->

# Run a server for your team

A deciduous server is two containers, the server and PostgreSQL, on one machine behind an HTTPS proxy. You start it once, then give each person a URL and a token. Every developer's CLI and every agent's MCP client writes to it, one workspace per repository.

This is the shape of the reference install: `https://bobbby.online/deciduous-mcp` is a Hetzner VM where Caddy proxies a path prefix to the server container. That install runs 1.0.12. The steps below were run on 2026-11-08 against the v1.1.0 release bundle, with the output shown, but not on a Linux VM: they ran under Docker Desktop on macOS, with Caddy in a container serving plain HTTP on `:80`. The Linux host, Docker Engine, `sha256sum` and Caddy's HTTPS certificate step were not run.

## What you need

- A Linux VM you can SSH to, with Docker Engine and Compose v2. If the `docker compose` plugin is missing, the setup script falls back to `docker-compose`.
- A DNS name for it, such as `deciduous.example.com`.
- Ports 80 and 443 open to the people who will connect. Leave every other port closed. The server listens only on `127.0.0.1`, and PostgreSQL has no host port at all.
- Roughly 1 GB of RAM free while the image builds.

## 1. Download and check the release bundle

Use the bundle from the same release as the CLI your team runs:

```bash
VERSION=v1.1.0
curl -fLO https://github.com/notactuallytreyanastasio/deciduous/releases/download/$VERSION/deciduous-mcp-docker.tar.gz
curl -fLO https://github.com/notactuallytreyanastasio/deciduous/releases/download/$VERSION/checksums.txt
grep deciduous-mcp-docker.tar.gz checksums.txt | sha256sum -c -
tar -xzf deciduous-mcp-docker.tar.gz
cd deciduous-mcp-docker
```

`sha256sum -c` should print `deciduous-mcp-docker.tar.gz: OK`. On macOS, use `shasum -a 256 -c -` instead.

## 2. Start it

```bash
./scripts/setup.sh
```

The bundle contains source code, not an image. `setup.sh` builds the server image on the VM: it pulls the Elixir builder and Debian base images, compiles the release, then starts PostgreSQL 17.11 and the server. Expect it to take a while the first time. On a slow connection it took 30 minutes, almost all of it spent downloading base images. When it finishes:

```
Deciduous is ready: http://127.0.0.1:24555/mcp
Credentials are in /opt/deciduous-mcp-docker/.env (DECIDUOUS_MCP_TOKEN).
Rerun this command to rebuild and upgrade. Your settings and database volume are preserved.
```

`setup.sh` returns only once `/ready` reports that the database is reachable and migrated. It picks a random port in 20000-32767 so that installs do not all compete for one fixed port. It does not check that the port is free. If Docker reports the port is already allocated, that port is already saved in `.env`, and setup ignores `DECIDUOUS_PORT` from the environment after the first run, so rerunning fails the same way: set `DECIDUOUS_PORT` in `.env` to another port and rerun setup. To choose the port yourself on the first run, use `DECIDUOUS_PORT=24555 ./scripts/setup.sh`.

Everything that defines the install is in `.env`, which is created with mode 0600:

```
COMPOSE_PROJECT_NAME=deciduous
DECIDUOUS_SERVER_MODE=docker
DECIDUOUS_DATABASE_MODE=local
DECIDUOUS_BIND_ADDRESS=127.0.0.1
DECIDUOUS_PORT=24555
DECIDUOUS_MCP_TOKEN='<64 hex digits>'
POSTGRES_PASSWORD='<64 hex digits>'
DATABASE_URL='ecto://deciduous:<password>@db:5432/deciduous'
DB_SSL=false
DB_SSL_VERIFY=full
DB_SSL_CA_FILE=
POOL_SIZE=10
```

Back this file up together with the database. The token in it is what every client presents, and `COMPOSE_PROJECT_NAME` names the PostgreSQL volume (`<project>_postgres-data`).

Check the install from the VM:

```bash
curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:24555/health   # 200
curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:24555/ready    # 200
curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:24555/mcp      # 401: no token
```

## 3. Put HTTPS in front of it

Clients on other machines need HTTPS. Here is a Caddy site on the VM that serves the server at the root of a domain:

```caddy
deciduous.example.com {
	reverse_proxy 127.0.0.1:24555
}
```

What the proxy must do is pass WebSocket upgrades through, because `deciduous remote watch` streams events over `/events`. Caddy does this by default. Earlier versions of this page set `flush_interval -1` and said MCP streaming needed it. It is not needed. The 1.1.0 server does not stream: `POST /mcp` returns plain JSON with a `Content-Length`, and `GET /mcp` is refused with 405 (`this server does not offer a server-to-client stream`). And Caddy already flushes immediately, whatever `flush_interval` says, when a response is `text/event-stream` or has no known `Content-Length` ([Caddy's `reverse_proxy` docs](https://caddyserver.com/docs/caddyfile/directives/reverse_proxy)), so a server that did stream would not need it either. Behind a Caddy 2.11 with no `flush_interval`, `remote init`, `add` and `remote watch` all worked.

To share a domain with something else, serve the server under a path, as the reference install does. `handle_path` strips the prefix, so the server still sees `/mcp` at its own root:

```caddy
example.com {
	handle_path /deciduous-mcp/* {
		reverse_proxy 127.0.0.1:24555
	}
	handle {
		respond 404
	}
}
```

Keep the final `handle` if nothing else is served on that domain. Without it, Caddy answers every other path with an empty 200. A developer who leaves the prefix off the URL and runs `deciduous remote init`, the first command a joining developer runs, then gets

```
Error: the server's response was not a claim: Failed to read JSON: EOF while parsing a value at line 1 column 0
```

instead of the CLI's clear `no such endpoint (404). Is the URL right, including any path prefix?`. `remote pull` says the same; `remote status` says `not a graph` in the same place. Both behaviours were tested. If the domain already serves something else, that site answers instead, and the error depends on what it returns.

If Caddy runs in a container, join it to the bundle's Compose network and proxy to `server:4000`. The network is `<COMPOSE_PROJECT_NAME>_default`, so `deciduous_default` for a default install: either `docker network connect deciduous_default <caddy-container>`, or, in Caddy's own compose file, list `deciduous_default` under the Caddy service's `networks:` and declare it at the top level with `external: true`. Port 4000 is the port inside the network; `DECIDUOUS_PORT` applies only on the host. The path-prefix form was tested this way, over plain HTTP: health, readiness, CLI writes, an MCP `add_node`, and `remote watch` all went through Caddy.

From your laptop:

```bash
curl -s -o /dev/null -w '%{http_code}\n' https://deciduous.example.com/health  # 200
curl -s -o /dev/null -w '%{http_code}\n' https://deciduous.example.com/mcp     # 401
```

`/health` and `/ready` are public on purpose, so that proxies and uptime checks can use them without a token. Every other route requires the token.

## 4. Hand out the URL and the token

Each person needs two things:

- the base URL: `https://deciduous.example.com`, or `https://example.com/deciduous-mcp` for the path form. This is a base URL, without `/mcp`. The CLI adds the paths it needs, and only the agent's MCP client is given `<base>/mcp`.
- the token: `DECIDUOUS_MCP_TOKEN` from `.env`, sent over a channel you trust.

From there, each person follows [Join a server](quickstart.md). There is one token for the whole server. Read [what that means](#what-one-token-means) before you hand it out.

## Use a managed PostgreSQL instead

If your provider runs PostgreSQL for you, start only the server container and point it at that database. You need a role that owns the database. Migrations run `ALTER DATABASE` to set planner defaults, so owning the schema alone is not enough.

```bash
export DATABASE_URL='ecto://deciduous:URL_ENCODED_PASSWORD@db.internal.example.com:5432/deciduous'
export DECIDUOUS_MCP_TOKEN="$(openssl rand -hex 32)"
export DB_SSL=true            # TLS to the database
export DB_SSL_CA_FILE=/app/certs/postgres-ca.pem   # only for a private CA; see below
./scripts/setup.sh --external-database
unset DATABASE_URL DECIDUOUS_MCP_TOKEN DB_SSL DB_SSL_CA_FILE
```

The server runs the pending migrations before it starts listening, and setup remembers that this install uses an external database. `DB_SSL_VERIFY` controls how much of the database server's certificate is checked:

| `DB_SSL_VERIFY` | libpq equivalent | What is checked |
|---|---|---|
| `full` (default) | `verify-full` | The certificate chain, and that the certificate names the host in `DATABASE_URL`. |
| `ca` | `verify-ca` | The chain only. Use this when you connect by an address the certificate does not name. |
| `none` | `require` | Nothing. The connection is encrypted but the server is not authenticated, and a warning is logged at every boot. |

For a private CA, put its PEM file at `certs/postgres-ca.pem` before the first run and export `DB_SSL_CA_FILE=/app/certs/postgres-ca.pem` with the rest, as above. Setup reads the TLS settings from the environment on the first run only and saves them in `.env`; on later runs it unsets them, so on an existing install edit `DB_SSL_CA_FILE` (or `DB_SSL`, `DB_SSL_VERIFY`) in `.env` and rerun setup. The server refuses to start if that file is missing or empty. Each boot logs the mode in effect:

```
Database TLS: verify-full: chain against DB_SSL_CA_FILE (/app/certs/postgres-ca.pem, 1 certificate(s)), certificate must name db.internal
```

Pages written for deciduous 1.0.4 said that the server never verified the database certificate. That stopped being true when `DB_SSL_VERIFY` was added. 1.1.0 verifies the chain by default (`deciduous_mcp/config/runtime.exs`).

The managed-database path was not run end to end for this page. The settings above are read from `runtime.exs` and `scripts/setup.sh`.

## Without Docker

The release also ships native server executables (`deciduous-mcp-linux-amd64` and `-linux-arm64`) with Erlang and Elixir built in, which run against any PostgreSQL. `deciduous_mcp/DEPLOY.md` in the repository covers the executable as the CLI installs it: a per-user service on a developer's machine (on Linux a systemd user unit under `~/.config/systemd/user`, which stops at logout unless lingering is on). It gives no system unit for a VM. The user unit that 1.1.0 writes on Linux also does not start: it puts `WorkingDirectory` in quotes, which systemd refuses as a fatal error. The fix (PR #330) ships in the next release. Until then, on a VM, use the Docker bundle above. The CLI's `remote setup --local` case is covered in [Without a shared server](local.md).

## What one token means

The bearer token is the server's only access control:

- **It covers every workspace on the server.** `X-Deciduous-Workspace` and the `workspace` argument route a request to a workspace; they do not authorize it. Anyone with the token can read and write every project on the server. If two teams must not see each other's graphs, run two servers.
- **There are no per-user identities.** A node on the server records the branch its writer reported, and nothing about who wrote it. Checked with `/export`: the metadata holds `branch` and `confidence`, and there is no author field. Use branch names to tell agents apart (see [Many agents, one graph](teams.md)).
- **`/events` also accepts the token as a `?token=` query parameter**, as a fallback for WebSocket clients that cannot set headers. Query strings end up in access logs, so turn off query logging on your proxy, or redact it.
- **Rotating the token logs out everyone at once.** See [Rotate the token](operating.md#rotate-the-token).

Backups, upgrades and rotation are covered in [Backups, upgrades, tokens](operating.md).

---

<!-- https://deciduous.dev/content/clients.md -->

# Connect your coding agents

Every client connects to the same thing: `<base>/mcp` over Streamable HTTP, with `Authorization: Bearer <token>`. What differs is where each client keeps that registration and whether it pins a workspace. The one thing to get right is that the agent's URL, token and workspace match what the CLI uses in `.deciduous/config.toml`; when they do not, the CLI and the agent write to two different graphs and neither complains.

| Value | Where it comes from | Example |
| --- | --- | --- |
| Base URL | `url` under `[remote]` in `.deciduous/config.toml` | `https://deciduous.example.com` |
| MCP URL | base URL + `/mcp` | `https://deciduous.example.com/mcp` |
| Token | the server's operator; stored by `deciduous remote login` | `<token>` |
| Workspace | `workspace` under `[remote]` | `my-app` |
| Branch | the current git branch, passed on every write | `main` |

Agents never need database credentials. One token opens every workspace on a server; see [Architecture](architecture.md).

## Claude Code

### User scope: one registration for every repository

This is the `claude mcp add` that `deciduous remote setup --url https://deciduous.example.com` runs (so do the interactive `remote setup` and a `deciduous init` that falls into it in a repository with no server yet), when Claude Code has no `deciduous` server:

```sh
claude mcp add --scope user --transport http deciduous https://deciduous.example.com/mcp \
  --header "Authorization: Bearer $(cat ~/.config/deciduous/credentials)"
```

`deciduous init` in a repository that already has `[remote]` does not run it: it checks the server, prints `Connected ... holds N nodes`, and registers nothing. So a teammate who clones a repository with `[remote]` in it runs `deciduous remote setup --url https://deciduous.example.com`, or the `claude mcp add` line above, themselves. `remote setup` with no flags and no terminal registers nothing either; it exits with an error listing the flags.

No workspace header: each tool call carries `workspace`, and the server's instructions tell the agent to take it from `[remote]` in `.deciduous/config.toml`, or else the repository root's directory name. The shell substitutes the token `remote login` stored when the command runs, so the token is written into `~/.claude.json`, outside every repository, in plain text. (`$DECIDUOUS_MCP_TOKEN` in its place works only if you exported that variable; `remote login` does not set it, and with it empty the command still succeeds and registers a header with no token.)

If a `deciduous` server is already registered, setup leaves it as it is and prints `Unchanged Claude Code already has a deciduous MCP server`. It decides that from the exit status of `claude mcp get deciduous` alone, which is 0 for a registration in any scope, whatever URL it points at, including a project `.mcp.json` still waiting for approval and a server that rejects its token. Read the `Status:` line every time you join a new server:

```sh
$ claude mcp get deciduous
deciduous:
  Scope: User config (available in all your projects)
  Status: ✔ Connected
  Type: http
  URL: https://deciduous.example.com/mcp
  Headers:
    Authorization: Bearer <token>

To remove this server, run: claude mcp remove deciduous -s user
```

A wrong or stale token looks like this (Claude Code 2.1.319, trimmed), and `get` still exits 0:

```
  Status: ✘ Failed to connect
  Issue: Server rejected the configured Authorization header (HTTP 401). ... Error detail: {"error":"unauthorized"}
```

`get` prints the token in clear text; do not paste its output anywhere. If `URL` is not your `[remote] url` + `/mcp`, or the status is `✘ Failed to connect`, `claude mcp remove deciduous -s user` and add it again as above. `No MCP server named "deciduous"` (exit 1) means nothing is registered; `remote setup --url` adds it, or run the `add` line yourself.

### Without the token in `~/.claude.json`

Claude Code's `headersHelper` runs a command when it connects and sends the headers it prints. This one reads the file `deciduous remote login` writes, so the token stays out of `~/.claude.json` and a new `remote login` reaches the agent too:

```sh
claude mcp add-json --scope user deciduous '{"type":"http","url":"https://deciduous.example.com/mcp","headersHelper":"printf '"'"'{\"Authorization\":\"Bearer %s\"}'"'"' \"$(cat ~/.config/deciduous/credentials)\""}'
```

Tested against a server with Claude Code 2.1.319: `claude mcp get deciduous` shows `Status: ✔ Connected` and no `Headers` lines, and `~/.claude.json` holds the helper command, not the token. If `XDG_CONFIG_HOME` is set, the credentials file is under it instead of `~/.config`.

### Local scope: a second server, with no file in the repository

Because there is one user-scope registration per machine, every repository on the machine talks to the same server through it. For a repository on a different server, register it in local scope, which is private to you, applies to that one project, and is also stored in `~/.claude.json`. Run this inside that repository:

```sh
claude mcp add --scope local --transport http deciduous https://other.example.com/mcp \
  --header "Authorization: Bearer $DECIDUOUS_MCP_TOKEN"
```

Export `DECIDUOUS_MCP_TOKEN` with the other server's token in that shell first. The credentials file holds one token, the first server's, so `$(cat ~/.config/deciduous/credentials)` would register the wrong one here; and with the variable unset the command still succeeds and registers a header with no token.

`claude mcp get deciduous` there then shows `Scope: Local config (private to you in this project)`. `remote setup` in that repository sees it and says `Unchanged`.

### Project scope: `.mcp.json`, pinned to one workspace

A `.mcp.json` in the repository root is shared with everyone who clones it, holds no secret, and pins the workspace:

```json
{
  "mcpServers": {
    "deciduous": {
      "type": "http",
      "url": "https://deciduous.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${DECIDUOUS_MCP_TOKEN}",
        "X-Deciduous-Workspace": "my-app"
      }
    }
  }
}
```

Claude Code expands `${DECIDUOUS_MCP_TOKEN}` from its own environment, so the variable must be set in the shell that launches `claude`; it does not read `~/.config/deciduous/credentials`. If the variable is unset, the server still loads with the literal text `${DECIDUOUS_MCP_TOKEN}`, and `claude mcp list` warns `Missing environment variables: DECIDUOUS_MCP_TOKEN`.

Until you approve it, the project server is not used. With no other `deciduous` registration, `claude mcp get deciduous` shows ``Status: ⏸ Pending approval (run `claude` to approve)``; with a user-scope one, `get` shows the user registration, and that is the one in use. When the same name is registered in several scopes, Claude Code uses one, in the order local, project, user ([its documentation](https://code.claude.com/docs/en/mcp)); checked here, a local registration was the one `get` showed in a repository that also had `.mcp.json` and a user server.

`X-Deciduous-Workspace` wins over the `workspace` argument of every call. Checked against a server: with the header set to `my-app`, `query_nodes({workspace: "some-other-repo"})` returned `my-app`'s nodes. That protects against an agent guessing the wrong workspace. It is not access control: the same token, without the header, reaches every workspace.

After any of these changes, restart Claude Code. The tools appear as `mcp__deciduous__add_node`, `mcp__deciduous__query_nodes` and so on, 21 of them ([MCP tools](mcp.md)).

## Clients deciduous writes no MCP config for

`deciduous init` takes `--claude`, `--opencode`, `--windsurf` and `--both`, and only the Claude Code path registers an MCP server. For every client below, nothing is connected until you add the entry yourself. `init` ends with `Restart your assistant so it connects to the server; it sends the logging instructions` for OpenCode and Windsurf too; for them that line does not apply.

The snippets below follow each client's current documentation (fetched 2026-11-08, cited per section). None of them was run against a server for this page.

### OpenCode

`deciduous init --opencode` writes `AGENTS.md`, `opencode.json` (which only adds `AGENTS.md` to the instructions), `.opencode/agents/deciduous.md`, `.opencode/commands/`, `.opencode/skills/`, an update-check plugin (`.opencode/plugins/version-check.ts`) and a custom tool, `.opencode/tools/deciduous.ts`.

None of these files knows about a server. In a project with `[remote]`, `.opencode/commands/sync.md` and `recover.md` still teach `deciduous sync` and `git add .deciduous/graph.json`, and with `--opencode` alone `AGENTS.md` says `deciduous sync    # Reconcile .deciduous/graph.json with teammates`. Ignore `/sync`'s git steps there; `deciduous remote status` and `deciduous remote pull` are the steps. (Under `--both`, `AGENTS.md` is converted from the server-aware `CLAUDE.md`; the `.opencode/` files are the same either way.)

The plugin and the custom tool were written for OpenCode 1.x. [OpenCode 2's migration guide](https://opencode.ai/v2/migrate-v1.md) says "V1 plugin implementations do not run in V2", so the update check does nothing there, and [its plugin guide](https://opencode.ai/v2/build/plugins/migrate-v1.md) does not say whether a V1 `tool()` file still loads.

In OpenCode 1.x the tool runs the `deciduous` CLI (`deciduous add goal ...`, `deciduous link ...`), and in a project with `[remote]` every CLI write goes to the server before the command exits. Without the tool, the agent reaches the server the same way by running `deciduous` in its shell.

Either way that needs `remote setup` run in the repository and at least one commit in it: in a repository with no commit, a CLI write is kept in `.deciduous/remote-log.jsonl` with `Nothing is sent until the first commit`, and sent by the next write after that commit or by `deciduous remote push` (a read such as `deciduous nodes` sends nothing, whatever the message says).

To give OpenCode the server's MCP tools as well, register the endpoint as a remote MCP server. This is the [V1 shape](https://docs.opencode.ai/docs/mcp-servers/), servers directly under `mcp`; [OpenCode 2 still reads it](https://opencode.ai/v2/migrate-v1.md) ("The V1 config format remains supported"), so it works in both:

```jsonc
{
  "$schema": "https://opencode.ai/config.json",
  "instructions": ["AGENTS.md"],
  "mcp": {
    "deciduous": {
      "type": "remote",
      "url": "https://deciduous.example.com/mcp",
      "enabled": true,
      "oauth": false,
      "headers": {
        "Authorization": "Bearer {env:DECIDUOUS_MCP_TOKEN}",
        "X-Deciduous-Workspace": "my-app"
      }
    }
  }
}
```

The [native V2 form](https://opencode.ai/docs/mcp-servers/) puts the server under `mcp.servers` (`"mcp": {"servers": {"deciduous": {...}}}`, without `enabled`). OpenCode's docs warn not to point V1 at a file converted to V2-only shapes, so use it only if everyone on the repository runs OpenCode 2.

OpenCode's syntax for an environment variable is `{env:NAME}`, not Claude Code's `${NAME}`. [An unset variable becomes an empty string](https://opencode.ai/docs/config/), so a missing `DECIDUOUS_MCP_TOKEN` shows up as a 401 from the server, not as a config error. `"oauth": false` stops OpenCode trying an OAuth login; deciduous only takes the bearer token. OpenCode also has `{file:~/...}` substitution, but the credentials file ends in a newline and OpenCode's docs do not say whether `{file:}` trims it, so it is not suggested here.

### Windsurf (Devin Local)

`deciduous init --windsurf` writes `.windsurf/rules/deciduous.md` (the workflow rules), `.windsurf/hooks.json` and `.windsurf/hooks/version-check.sh` (a version check on `pre_write_code`), and the Claude Code files (`CLAUDE.md`, `.claude/`): `--windsurf` without `--opencode` means Claude Code plus Windsurf. `deciduous init --opencode --windsurf` writes the Windsurf and OpenCode files and no Claude Code files.

The rules file does not know about a server: in a project with `[remote]` it still says `deciduous sync    # Reconcile .deciduous/graph.json with teammates`. Use `deciduous remote status` and `deciduous remote pull` instead.

Windsurf's documentation now redirects to [Devin Local's](https://docs.devin.ai/desktop/cascade/mcp). It still loads `.windsurf/rules/*.md` ("The legacy `.windsurf/rules/*.md` ... files are imported by default"), but it documents hooks only in `.devin/hooks.v1.json`, so whether `.windsurf/hooks.json` still runs is unconfirmed.

Devin Local reads MCP servers from `~/.config/devin/mcp_config.json` (user), `.devin/mcp_config.json` (project, committed) or `.devin/mcp_config.local.json` (project, gitignored). Its pages give no remote-server example; [the Devin CLI's configuration reference](https://docs.devin.ai/cli/extensibility/mcp/configuration.md) names the keys `url`, `transport` and `headers` under `mcpServers`, which gives this shape:

```json
{
  "mcpServers": {
    "deciduous": {
      "url": "https://deciduous.example.com/mcp",
      "transport": "http",
      "headers": {
        "Authorization": "Bearer <token>",
        "X-Deciduous-Workspace": "my-app"
      }
    }
  }
}
```

It holds the token itself, so put it in the user file or `.devin/mcp_config.local.json`, never in `.devin/mcp_config.json`. Devin documents `${env:VAR}` only for OAuth fields. Older Windsurf builds read `~/.codeium/windsurf/mcp_config.json` with `serverUrl` instead of `url`, according to third-party guides, not Windsurf's own pages. Without MCP, the agent can still write through the CLI from its terminal, which reaches the server.

### Cursor

[Cursor](https://cursor.com/docs/context/mcp) reads `.cursor/mcp.json` in the project or `~/.cursor/mcp.json`, and resolves `${env:NAME}` in `url` and `headers`:

```json
{
  "mcpServers": {
    "deciduous": {
      "url": "https://deciduous.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${env:DECIDUOUS_MCP_TOKEN}",
        "X-Deciduous-Workspace": "my-app"
      }
    }
  }
}
```

### Codex CLI

[Codex](https://learn.chatgpt.com/docs/extend/mcp?surface=cli) reads `~/.codex/config.toml`, or `.codex/config.toml` in a project it trusts. `bearer_token_env_var` names the variable it sends as `Authorization: Bearer`:

```toml
[mcp_servers.deciduous]
url = "https://deciduous.example.com/mcp"
bearer_token_env_var = "DECIDUOUS_MCP_TOKEN"
http_headers = { "X-Deciduous-Workspace" = "my-app" }
```

### VS Code

[VS Code](https://code.visualstudio.com/docs/agents/reference/mcp-configuration) reads `.vscode/mcp.json`, with servers under `servers` and a token it prompts for once through an input:

```json
{
  "inputs": [
    { "type": "promptString", "id": "deciduous-token", "description": "deciduous token", "password": true }
  ],
  "servers": {
    "deciduous": {
      "type": "http",
      "url": "https://deciduous.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${input:deciduous-token}",
        "X-Deciduous-Workspace": "my-app"
      }
    }
  }
}
```

The same page describes a portable format, `mcpServers` in a workspace-root `.mcp.json`, read by Copilot harness sessions, so a repository with the Claude Code `.mcp.json` above may already show up there.

### Claude Desktop and claude.ai

These take the server as a [custom connector](https://claude.com/docs/connectors/custom/add-unlisted) added by URL under Customize > Connectors, not as a local file. The URL must be an HTTPS address reachable from the internet; a server inside a private network needs Anthropic's MCP tunnels. Choose Authentication **No sign-in** and add `Authorization` with the value `Bearer <token>` under **Request headers**, which that page says is "in beta and available to a limited set of organizations". `authorization` is on the standard list, but a custom name such as `X-Deciduous-Workspace` needs Anthropic's approval, so name the workspace in the conversation instead.

## Any other MCP client

The server speaks Streamable HTTP. A client must:

- `POST` JSON-RPC to `<base>/mcp` with `Authorization: Bearer <token>`.
- Send `Accept: application/json, text/event-stream`.
- Keep the `mcp-session-id` header from the `initialize` response and send it on every later request.
- Send `notifications/initialized` after `initialize`, before any other call. Skip it and the next request fails with `Session not found` and a message saying the session expired or the server restarted, which it did not.

This is the handshake, done by hand:

```sh
$ curl -s -D - https://deciduous.example.com/mcp \
    -H "Authorization: Bearer $DECIDUOUS_MCP_TOKEN" \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json, text/event-stream' \
    -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"probe","version":"0"}}}'
...
mcp-session-id: session_GOYlpWIM6imVxCMqh0M=
...
```

The result's `serverInfo` is `{"name": "deciduous-mcp", "version": "1.1.0"}`, and its `instructions` field carries the logging rules the agent should follow (quoted on [For agents](for-agents.md)). A client that shows the instructions to its model gets the workflow without any project file.

Any other client takes the same URL and headers in its own config format. Keep the token out of any file you commit.

### Not the same thing: `deciduous mcp`

`deciduous mcp` is a different MCP server: it runs on stdin/stdout, on the machine, against the local database, with 34 tools under different names (`link_nodes`, `search_nodes`, `trace_chain`, `list_nodes`, ...). If your agent's tool list has those names, it is talking to this one, not to `<base>/mcp`.

In a project with `[remote]` its writes do reach the server, the same way CLI writes do (an `add_node` through it showed up as In sync in `remote status`). But it sends no `instructions` on connect, and its tools take local integer ids. Prefer the HTTP endpoint; use `deciduous mcp` only for a client that cannot speak HTTP, or for the no-server mode on [Local](local.md).

## Making the CLI and the agent agree

Three settings have to match, and nothing checks that they do:

1. **URL.** `[remote] url` + `/mcp` is the URL in the client's registration (`claude mcp get deciduous | grep -E 'Status|URL'`; unfiltered, it prints the token).
2. **Token.** The CLI uses `$DECIDUOUS_MCP_TOKEN` if it is set, otherwise `~/.config/deciduous/credentials` (under `$XDG_CONFIG_HOME` if that is set). The client uses whatever its registration holds. A stale `DECIDUOUS_MCP_TOKEN` in your shell overrides a fresh `remote login`.
3. **Workspace.** `[remote] workspace` is what the agent passes as `workspace`, or what the `X-Deciduous-Workspace` header says.

Then prove it in both directions. Write a goal with the CLI and ask the agent to find it with `query_nodes`; the `change_id` it reports starts with the CHANGE column `deciduous nodes` prints. Have the agent write a node and run `deciduous remote status`: the node is listed under `Only on the server`, and `deciduous remote pull` brings it down. If the agent's node is not there, it went to another server or another workspace. `list_workspaces` on the agent's side shows where.

One trap in that check: the two sides use different ids. The CLI shows small local integers and an 8-character change_id prefix; the server's tools use UUIDs. `add_node`'s `parent_id` must be the server UUID from `query_nodes`. A change_id is refused:

```
parent_id is not a node id: "b1710c03"
```

---

<!-- https://deciduous.dev/content/for-agents.md -->

# For agents: setting up and using deciduous

This page is written to you, the coding agent that was told "set up deciduous here" or "use deciduous". The graph lives on a server the user's team runs; your job is to connect this repository to that server, prove the connection, and then write to the graph while you work. The one thing you must not do is guess which server. Ask.

Everything here is true of deciduous 1.1.0. The output shown was captured from it.

## First, find out what is already there

Run these from the repository root and read the results before doing anything else:

```sh
deciduous --version                      # deciduous 1.1.0
git rev-parse --show-toplevel
cat .deciduous/config.toml 2>/dev/null   # look for a [remote] table
claude mcp get deciduous | grep -E 'Status|URL'   # Claude Code only; read-only
```

Filter `claude mcp get`: unfiltered, it prints the registration's `Authorization: Bearer` header with the whole token, which would put the token in your context and the session transcript. `claude mcp list` shows the URL and status of every server without headers.

- **`[remote]` with `url` and `workspace` is present:** the repository is configured, but this machine may not be. If `claude mcp get` printed `No MCP server named "deciduous"`, or there is no token on this machine (question 2 below), the user stores the token and you run `deciduous remote setup --url <the url in [remote]>`. The URL is already chosen, so there is nothing else to ask. Then go to [Verify](#verify-the-connection).
- **No `.deciduous/`, or no `[remote]`:** it needs setting up. Ask the user first (next section).
- **Your tool list has `mcp__deciduous__add_node`, `query_nodes`, `check_activity`:** you are connected to a deciduous server over HTTP. **It has `link_nodes`, `search_nodes`, `trace_chain`:** you are on the local `deciduous mcp` stdio server instead, which has different tools and sends no logging instructions; tell the user.

## Ask the user, never invent

Before any setup command, ask:

1. **Which server?** Its base URL, for example `https://deciduous.example.com`. Do not make one up, do not assume `http://127.0.0.1:4000`, and do not pick `remote setup --local` because it needs no answer. `--local` installs a server and a background service on this machine; that is the user's decision, covered on [Local](local.md). (On Linux, 1.1.0's systemd unit for `--local` and `--database-url` does not start: systemd rejects its quoted `WorkingDirectory=`. The fix, [#330](https://github.com/notactuallytreyanastasio/deciduous/pull/330), is not yet released.)
2. **Is the token already on this machine?** It is if `~/.config/deciduous/credentials` exists or `DECIDUOUS_MCP_TOKEN` is set. If not, the user gets it from whoever runs the server and stores it themselves:
   ```sh
   deciduous remote login --url https://deciduous.example.com
   ```
   It reads the token from stdin and checks it against the server before storing it. Never ask the user to paste the token into the conversation, never put it in a file in the repository, a node, or a commit. Do not run `remote login` or `remote logout` yourself: there is one stored token per machine, and login replaces it for every repository on the machine.
3. **Should the integration files be committed** (`CLAUDE.md`, `.claude/`), or kept to this checkout?

If the user says they have no server and want one, point them at [Run a server](run-a-server.md); do not stand one up unasked.

## Set up

With the URL from the user and the token stored:

```sh
deciduous remote setup --url https://deciduous.example.com
deciduous init
```

Order matters. Your shell is not a terminal, and `init` in a repository with no `[remote]` cannot ask where the graph lives. It writes its files, then fails:

```
Error: /path/to/my-app has no server configured ([remote] in .deciduous/config.toml), and there is no terminal to ask where its graph should live. Choose one:

    deciduous remote setup --local                  # this machine: a background service, PostgreSQL on localhost:5432
    deciduous remote setup --database-url <url>     # this machine's server, a PostgreSQL you name
    deciduous remote setup --docker-postgres        # this machine: PostgreSQL and the server in Docker
    deciduous remote setup --url <url>              # a server someone else runs
```

That is a question for the user, not a menu for you. Run `remote setup --url` with the URL they gave you, then `init` again; it skips files that exist. Do not set `DECIDUOUS_NO_SERVER=1` to get past it: that opts the project out of a server altogether, which is the user's choice ([Local](local.md)).

Use `init --opencode`, `--windsurf` or `--both` if the user runs those assistants ([Clients](clients.md)).

What can go wrong at this step, by message:

| Message | Cause | What to do |
| --- | --- | --- |
| ``no token: set DECIDUOUS_MCP_TOKEN or run `deciduous remote login --url <base>` first`` | No token on this machine | Ask the user to run `remote login` |
| `server rejected the token (401) ... Nothing was stored or written.` | Wrong token for this server | Tell the user; nothing changed |
| `cannot reach <url>: ... timed out reading response` | `/health` took over 15 s | Run it once more, then report it |
| `Warning: the local write succeeded but could not be sent: ... this repository has no commit yet` | The server ties a workspace to the repository's root commit | After the user's first commit, `deciduous remote push` |

### Claude Code's registration may point elsewhere

`remote setup` registers the server with Claude Code only if no server called `deciduous` is registered. If one is, it prints `Unchanged Claude Code already has a deciduous MCP server` and leaves it alone, even when it points at a different server. Compare the `URL` from `claude mcp get deciduous | grep -E 'Status|URL'` with `[remote] url` + `/mcp`. If they differ, your MCP writes and the CLI's go to two different graphs.

Do not change the registration yourself; it is the user's machine-wide configuration. Tell them, and give them the fix:

```sh
claude mcp remove deciduous -s user
claude mcp add --scope user --transport http deciduous https://deciduous.example.com/mcp \
  --header "Authorization: Bearer $(cat ~/.config/deciduous/credentials)"
```

`$(cat ...)` reads the token `remote login` stored. Do not hand them `$DECIDUOUS_MCP_TOKEN` unless they exported it: `remote login` does not set it, and with it empty the registration is `Authorization: Bearer` with no token, which the server answers with 401.

Claude Code loads MCP servers at start. A new or changed registration reaches you only after the user restarts it, so until then you cannot see the tools; say so instead of looking for them.

## Verify the connection

Report each check to the user as pass or fail, with its output. A setup that writes to the wrong place is worse than one that fails.

1. **CLI and server agree.**
   ```
   $ deciduous remote status
   Remote: https://deciduous.example.com
   Workspace: my-app
   Log: 0 write(s) waiting, 0 rejected  (...)

                    local    server
     nodes              1         1
     edges              0         0

   In sync: no writes waiting, and every node, edge and document matches field by field.
   ```
   Exit 0 with the `In sync` line is a pass. Exit 0 with `Local only: no remote configured` means this checkout has no `[remote]`: a fail. Exit 1 is anything else.
2. **Your MCP connection reaches the same server.** `claude mcp get deciduous | grep -E 'Status|URL'` shows `[remote] url` + `/mcp`, `Status: ✔ Connected`.
3. **Your writes land in this workspace.** If you ran `remote setup` in this session, or the registration changed, you do not have the tools yet: report checks 1 and 2, ask the user to restart Claude Code, and do this check in the new session. Do not substitute a CLI write; it proves the CLI's path, which check 1 already did. Write a node the user's request actually needs, usually the goal for their request with their message verbatim in `prompt`, or an option under it, with `add_node`, then run `deciduous remote status`. Your node appears under `Only on the server`:
   ```
   Only on the server (1)
     option cad0b58d "Token bucket per API token in Redis"

   Differs: `deciduous remote pull` takes the server's side.
   ```
   `deciduous remote pull` brings it into the local copy, and status is In sync again. If your node is not listed, it went to another workspace or another server: `list_workspaces` shows where.

Do not write a probe node such as "connection checked": it is your process, not a project decision, and with no parent it is an orphan `find_orphans` reports. If you wrote one anyway, remove it with `delete_node` once `remote status` has shown it.

## While you work

The server sends you these rules when you connect. They are the rules; the rest of this section only adds detail.

> - The user asks for something: a goal, with their message verbatim in `prompt`.
> - You see more than one way to do it: options. You pick one: a decision whose title names what it beat.
> - You change code or config: an action. It works or fails: an outcome with the number or the error.
> - You learn a fact that changes the plan: an observation. An earlier choice turns out wrong: a revisit.

**Session start: read before writing.** `query_nodes` with `workspace` and `branch`, then `ask_graph` with the topic of the request. `check_activity` shows who else has been writing where in the last five minutes. If the work continues an existing goal, put new nodes under it rather than starting a second one. If other agents are working in parallel, `read_messages` with `unanswered_for` set to your label.

**Every write carries `workspace` and `branch`.** The workspace is `workspace` under `[remote]` in `.deciduous/config.toml`; without one, the repository root's directory name, also from a worktree (a worktree under `.claude/worktrees/fix-x` belongs to the repository, not to a workspace called `fix-x`). The branch is the current git branch. If the client sends an `X-Deciduous-Workspace` header, that wins over your argument.

**Create and link in one call.** `add_node` with `parent_id` makes the node and its edge together. `parent_id` is the server's UUID for the parent, as `query_nodes` returns it in `id`; a CLI change_id is refused (`parent_id is not a node id: "b1710c03"`). Never send `add_edge` in the same batch as the `add_node` whose id it needs: the id does not exist yet. To make a retried `add_node` safe, give it a `change_id` (a UUID you generate); sending it again returns the node already made.

**One step, one call.** `capture_conversation_turn` writes a step's goal, observations, decision, action and outcome together, all or nothing; `parent_node_id` puts it under the goal you are working on.

**Commits.** After a commit, log the action or outcome with `commit` set to the hash.

**Do not log your own process:** reading files, searching, planning, "starting work". The test: would the user put it in a PR description?

**When a line of work ends:** `close_thread` writes the closing outcome and can mark the goal completed; then `find_orphans` and link anything it lists except root goals. Tell the user which nodes you added.

**Another session writing your branch does not block you.** Agents in parallel coordinate on the message board (`post_message`, `read_messages`, `reply_to`), never in a scratch file. [The message board](board.md) has the rules, and [Teams](teams.md) the rest of working in parallel.

### Writing from the CLI instead

In a project with `[remote]`, `deciduous add` and `deciduous link` write to the server before the command exits, so a shell is a fallback when MCP is not available. CLI node references are local ids, change_id prefixes, or server UUIDs (a UUID resolves only once the node is in the local cache; run `deciduous remote pull` first if an MCP tool made it):

```sh
deciduous add goal "Add rate limiting to the public API" -c 90 -p "<the user's message, verbatim>"
deciduous link b1710c03 2 -r "possible approach"
```

The local copy does not see MCP writes until it pulls. Linking the CLI to a node you just made through MCP fails until `deciduous remote pull`:

```
$ deciduous link 80f8630d 6 -r "implements the decision"
Error: No node has a change_id starting with '80f8630d'. Run 'deciduous sync' if a teammate created it.
It is not a server id in workspace my-app either.
$ deciduous remote pull
...
$ deciduous link 80f8630d 6 -r "implements the decision"
Created edge 5 (7 -> 6 via leads_to)
```

(With a server, the fix is `remote pull`, not the `sync` the message names.)

More: [the workflow](workflow.md), [recovering context](recovery.md), [MCP tools](mcp.md), [troubleshooting](troubleshooting.md).

---

<!-- https://deciduous.dev/content/workflow.md -->

# Record the work as goal, options, decision, action, outcome

A useful graph answers two questions for whoever comes next: what was asked for, and what has already been tried. Write each node at the moment it happens, on the server everyone shares: an agent through the server's MCP tools, a person through the `deciduous` CLI in a repository whose `.deciduous/config.toml` has a `[remote]`. Both land in the same workspace, with the same `change_id` on every node, so either side can link to what the other wrote.

```text
goal -> option(s) -> decision -> action -> outcome
                                      \-> observation (anywhere)
```

The examples use workspace `my-app`. Everything shown was run against a 1.1.0 server; ids are the ones it returned.

## The goal: the request, verbatim

Put the user's exact words in `prompt`. A summary loses what the next session needs to know.

MCP:

```javascript
add_node({
  workspace: "my-app", branch: "agent-api",
  node_type: "goal", status: "active",
  title: "Validate create-item requests",
  prompt: "Add request validation and tests for the create-item endpoint."
})
```

```json
{ "id": "32d05bcb-1b2b-4b7b-b3b8-170a8aa8b7fb", "change_id": "5ca33b18-c27e-4723-9610-3874a592fb7a",
  "created": true, "status": "active", "message": "Node created successfully" }
```

CLI (the branch is detected from git; `--prompt-stdin` takes a multi-line message from a heredoc):

```console
$ deciduous add goal "Bound retries for failed requests" -c 90 -p "Stop retrying forever when the upstream API is down."
Warning: Prompt is only 52 chars. This looks like a summary, not a full prompt.
         Capture the verbatim user message for better context recovery.
Created node 1 (type: goal, title: Bound retries for failed requests) [confidence: 90%] [prompt: 52 chars] [branch: main]
```

The warning fires on any prompt shorter than 200 characters; it does not block the write. Nodes default to `pending`. `add_node` takes `status: "active"`; the CLI needs a second command, `deciduous status 1 active`.

Keep credentials out of prompts. Whoever holds the server token can read every prompt in every workspace (see [Architecture](architecture.md)).

## Options and the decision

The decision is only written once an option is actually chosen. Its title should say what it beat.

MCP has one call that writes the decision, its options and the edges in a single transaction:

```javascript
log_decision({
  workspace: "my-app", branch: "agent-api",
  parent_node_id: "32d05bcb-1b2b-4b7b-b3b8-170a8aa8b7fb",
  title: "Validate at the HTTP boundary, not after the write",
  rationale: "Reject malformed requests before they reach the service layer.",
  chosen_option: {title: "Validate at the HTTP boundary", description: "Return 422 with stable field error codes."},
  rejected_options: [{title: "Validate after the database write",
                      reason: "The service would receive invalid input and rely on rollback."}]
})
```

```json
{ "decision_id": "d63d2ce0-d91f-406e-9c4f-7253ee438c59",
  "chosen":   {"id": "894c65c3-...", "title": "Validate at the HTTP boundary"},
  "rejected": [{"id": "1644a09f-...", "title": "Validate after the database write"}] }
```

Know the shape it writes, because it is not the canonical flow: the edges run goal -> decision, then decision -> option (`chosen`) and decision -> option (`rejected`), with each `reason` as the edge rationale. The decision is created `completed`, the chosen option `completed`, the rejected one `rejected`.

`capture_conversation_turn` does the same for options inside a larger step. Pass the options as objects and mark the winner, or every option is recorded as rejected:

```javascript
options_considered: [{title: "Codes in a shared enum", chosen: true}, {title: "Codes as string literals"}],
decision: {title: "Shared enum over string literals", rationale: "Tests import the same enum"}
```

With `options_considered: ["RFC 7807 problem+json", "Ad-hoc {error: string}"]` (plain strings) both options came back with `"chosen": null` and both got a `rejected` edge from the decision, including the one that was picked.

The CLI writes one node per command and links them by hand, so it writes the flow in the canonical direction, option -> decision:

```console
$ deciduous add option "Cap the attempt count" -c 70
Created node 2 (type: option, title: Cap the attempt count) [confidence: 70%] [branch: main]
$ deciduous add option "Use an overall deadline" -c 80
Created node 3 (type: option, title: Use an overall deadline) [confidence: 80%] [branch: main]
$ deciduous link 1 2 -r "possible approach"
$ deciduous link 1 3 -r "possible approach"
$ deciduous add decision "Use an overall deadline, not an attempt cap" -c 80 -d "A slow attempt can exceed the wait budget under an attempt cap."
Created node 4 (type: decision, ...)
$ deciduous link 3 4 -t chosen -r "bounds total wait even when attempts are slow"
Created edge 3 (3 -> 4 via chosen)
$ deciduous link 2 4 -t rejected -r "a slow attempt can exceed the budget"
Created edge 4 (2 -> 4 via rejected)
```

The two shapes are not interchangeable everywhere. `deciduous writeup` builds a decision's "Options considered" list only from edges that run decision -> option, the shape `log_decision` writes, so a decision linked option -> decision as above appears in a writeup without its options.

The numbers are local ids, valid only in this checkout's cache. To refer to a node someone else wrote, use the 8-character `CHANGE` column from `deciduous nodes` or the server's UUID; `link`, `status`, `show` and `doc attach` accept all three.

## The action: before you edit

MCP: `parent_id` creates the node and its incoming edge in one transaction.

```javascript
add_node({
  workspace: "my-app", branch: "agent-api",
  node_type: "action", status: "active",
  title: "Implement request validation at the route boundary",
  files: ["src/http/items.ts"],
  parent_id: "d63d2ce0-d91f-406e-9c4f-7253ee438c59",
  rationale: "Implement the selected boundary"
})
```

```json
{ "id": "de6ccf4c-877b-406d-a41a-5474d8c764ec", "change_id": "be04811f-807f-452f-ae1b-873eb51304d5",
  "created": true, ... }
```

Do not send `add_node` and an `add_edge` that needs its id in the same batch. The id does not exist yet, and the server says so:

```text
from_node_id is not a node id: "PLACEHOLDER". To link a node you are creating now, pass parent_id
to add_node instead; an id must come from a previous answer, not be written ahead of it
```

A non-goal written without `parent_id` is accepted, and the reply carries `suggested_parents`: up to five ranked guesses with the signals behind each (type fit, text similarity, same branch, shared files, recency, open status), and `suggested_parents_hint` names the `add_edge` call that would link one. Nothing is linked for you.

CLI:

```console
$ deciduous add action "Apply a 30s deadline to the retry loop" -c 85 -f "src/retry.rs,tests/retry.rs"
$ deciduous link 4 5 -r "implement the chosen option"
```

`--commit` takes `HEAD`, a branch, a tag or a hash prefix and stores the full hash; a rev git cannot resolve is refused. The server cannot see your checkout, so over MCP pass the real hash in `commit`; it stores whatever string you send.

## Observations: what changes the plan

Here the tests agent records that it is reusing a decision from the API agent's branch. `183e9e9a-...` is that decision, "Use RFC 7807 problem+json over an ad-hoc error object", written by the `capture_conversation_turn` call under [One step, one call](#one-step-one-call).

```javascript
log_observation({
  workspace: "my-app", branch: "agent-tests",
  title: "Reuse the RFC 7807 shape in fixtures",
  related_to: "32d05bcb-1b2b-4b7b-b3b8-170a8aa8b7fb",
  took_from: "183e9e9a-153a-4141-9fb2-8312fe486012",
  why: "The API side already emits problem+json; fixtures that match it keep the tests honest."
})
```

`related_to` and `took_from` take a server UUID or a full `change_id`. An 8-character prefix is refused over MCP (`took_from is not a node id: "9ad1b0b7"`), although the CLI accepts one. `took_from` draws a `took_from` edge from the source node to the new observation, with `why` as its rationale; [Teams](teams.md#borrowing-across-branches-tookfrom) covers it.

## The outcome: the number or the error

The parent is the action `add_node` created above (`de6ccf4c-...`).

```javascript
close_thread({
  workspace: "my-app", branch: "agent-api",
  parent_node_id: "de6ccf4c-877b-406d-a41a-5474d8c764ec",
  title: "Invalid requests return 422 with field codes",
  description: "npm test -- tests/items.test.ts: 8 passed.",
  success: true,
  lessons_learned: ["The router already parses JSON before handlers run"]
})
```

`success: true` writes a `completed` outcome under the parent; `success: false` writes a `rejected` one. Each `lessons_learned` entry becomes an observation under the outcome; each `next_steps` entry becomes a `pending` goal linked under the outcome. `next_steps` entries must be objects (`{"title": "...", "description": "..."}`); unlike `lessons_learned`, a plain string is refused with `next_steps[0] must be an object ... nothing was written`. `goal_node_id` marks that goal `completed` unless `success` is `false`, so pass it only when the whole goal is done, not when your part is.

CLI:

```console
$ deciduous add outcome "Retry loop stops at the deadline" -c 90 -d "cargo test retry: 4 passed"
$ deciduous link 5 6 -r "test result"
$ deciduous status 6 completed
```

`deciduous status` accepts `pending, active, completed, rejected, superseded, abandoned`. Its 1.1.0 `--help` lists only the first four; main's lists all six. Either way a wrong value is refused with the full list: `unknown status 'bogus'; expected one of: pending, active, completed, rejected, superseded, abandoned`.

## One step, one call

`capture_conversation_turn` writes a step's goal, observations, options, decision, action and outcome together, all or nothing, linked to each other and to `parent_node_id`:

```javascript
capture_conversation_turn({
  workspace: "my-app", branch: "agent-api",
  parent_node_id: "32d05bcb-1b2b-4b7b-b3b8-170a8aa8b7fb",
  summary: "Chose the error format and wrote it",
  observations: ["Clients already parse RFC 7807 problem documents"],
  options_considered: [{title: "RFC 7807 problem+json", chosen: true}, {title: "Ad-hoc {error: string}"}],
  decision: "Use RFC 7807 problem+json over an ad-hoc error object",
  action: "Emit problem+json from the validation middleware",
  outcome: "Validation errors render as problem+json; 3 snapshot tests pass"
})
```

It wrote parent -> observation, parent -> decision, decision -> each option, decision -> action -> outcome.

## Retries and typos

A tool refuses an argument it does not have and names the ones it does, and nothing is written:

```text
add_node has no argument "parent" (did you mean parent_id?). Its arguments are: branch, change_id,
commit, confidence, description, edge_type, files, node_type, parent_id, prompt, rationale, status,
title, workspace; nothing was written
```

To make a retried `add_node` safe, give it a `change_id` (any UUID). The second call with the same one returns the first node, `"created": false`, and does not duplicate the edge:

```json
{ "id": "c2bc238e-...", "created": false,
  "message": "Node already exists with change_id 11111111-2222-4333-8444-555555555555; nothing new was created (linked under parent_id)" }
```

## Changing a node

`update_node` changes title, description, status or metadata. `metadata` is merged: keys you send are set, a key sent as `null` is removed, the rest are kept. Sending `{"commit": "0123abc"}` to an action with `branch` and `files` left all three in place. (Older docs said it replaced the map. It does not.)

When an approach is abandoned, do not edit the old decision into the new one. Record why and pivot; [History](history.md) shows both the one-command CLI pivot and the MCP calls.

## Before you stop

```javascript
find_orphans({workspace: "my-app"})
```

```json
{ "count": 1, "orphans": [{ "id": "e0ff0733-...", "node_type": "observation", "title": "Orphan probe" }] }
```

Link each orphan to its real cause, not to whichever root makes the list empty. `suggest_parents: true` adds ranked guesses for the first 25.

From the CLI, `deciduous remote status` is the check: it exits 0 and prints `In sync` when every write reached the server, and exits 1 listing what differs otherwise. Writes are sent before each command exits, so it normally says:

```console
$ deciduous remote status
Remote: https://deciduous.example.com
Workspace: my-app
Log: 0 write(s) waiting, 0 rejected  (.../.deciduous/remote-log.jsonl)

                 local    server
  nodes              6         6
  edges              6         6

In sync: no writes waiting, and every node, edge and document matches field by field.
Themes and tags are not sent to the server, so they are not compared.
```

Nodes an agent wrote over MCP show up as `Only on the server` until you run `deciduous remote pull`; that is a stale cache, not lost work. [Recovery](recovery.md) covers reading the graph back.

---

<!-- https://deciduous.dev/content/teams.md -->

# Many agents, one workspace

Every agent and every person on a project writes to the same workspace on the same server, each on its own git branch. Nothing locks: two sessions writing one branch both succeed and their nodes interleave. What keeps them from colliding is that each can see the others, through `check_activity`, [the message board](board.md), and `took_from` edges that say whose idea a node built on.

## One workspace per repository

The workspace is `workspace` under `[remote]` in `.deciduous/config.toml`. Commit that file, and every clone and worktree writes to the same graph:

```toml
[remote]
url = "https://deciduous.example.com"
workspace = "my-app"
```

`deciduous init` writes a `.gitignore` that ignores `.deciduous/*` except `config.toml` and `graph.json`. `remote init` on its own writes none: after it, `git status` shows all of `.deciduous/` untracked, cache and write log included. If you joined with `remote init` only, stage `.deciduous/config.toml` by name and ignore the rest of `.deciduous/` yourself.

The server ties a workspace to the root commit of the first repository that claims it. `remote init` claims at once, before anything is written. `remote setup` does not: the claim is made by the next `remote status`, `remote pull` or write. A clone shares that root, so it is let in:

```console
$ deciduous remote init https://deciduous.example.com --workspace my-app
Remote: https://deciduous.example.com
  workspace: my-app
  claim: verified (by this repository's root commit)
```

An unrelated repository that merely has the same directory name is refused, which is what stops two projects called `api` on one server from writing one graph by accident:

```console
$ deciduous remote init https://deciduous.example.com
Error: workspace "my-app" on https://deciduous.example.com belongs to another repository: an unrelated
project whose directory is also called my-app (the name is the directory name, lowercased) claimed it
first, and this repository shares none of its root commits.
...
Nothing was written; the project is unchanged.
```

Naming the workspace explicitly with `--workspace` is how you say two repositories really should share one graph. The server then answers `claim: adopted` and accepts writes from both. A repository with no commit yet cannot be checked, so its writes wait in the log until the first commit.

## Worktrees

A worktree whose checkout includes `.deciduous/config.toml` uses it. One made from a commit before that file existed inherits the main checkout's:

```console
$ git worktree add -b old-wt ../my-app-old HEAD~1 && cd ../my-app-old
$ deciduous remote status
Remote: https://deciduous.example.com
Workspace: my-app
From: this worktree's config names no server; its writes go to the main checkout's (.../my-app/.deciduous/config.toml)
```

Each worktree keeps its own local cache (`.deciduous/deciduous.db`), so a new worktree starts empty: run `deciduous remote pull` there before `deciduous nodes`. The server holds one copy; the caches are per directory.

Agents need the same name. The server's instructions tell an agent to read `workspace` from `.deciduous/config.toml`, and to fall back to the repository root's directory name, not the worktree's. If an agent client could still guess wrong, pin it: an `X-Deciduous-Workspace` header on the MCP connection overrides the `workspace` argument on every call ([Clients](clients.md)).

## Branches

Pass the real git branch on every MCP write. The server cannot see your checkout. The CLI fills it in from git (`[branch: agent-tests]`); `-b` overrides it.

Two worktrees for two agents:

```bash
git worktree add -b agent-api   ../my-app-api   HEAD
git worktree add -b agent-tests ../my-app-tests HEAD
```

Worktrees start from the commit you name and do not carry uncommitted changes.

## check_activity: who is writing where

Call it before a burst of writes and after each milestone.

```javascript
check_activity({workspace: "my-app"})
```

Trimmed, from a workspace with two MCP sessions and the CLI writing:

```json
{
  "sessions": [
    { "session": "GOYltCLK", "client": "docs-work", "branch": "agent-api",   "is_you": true,  "seconds_ago": 0 },
    { "session": "GOYljadZ", "client": "docs-work", "branch": "agent-api",   "is_you": false, "seconds_ago": 0 },
    { "session": "GOYljadZ", "client": "docs-work", "branch": "agent-tests", "is_you": false, "seconds_ago": 12 },
    { "session": "cli:4c3b", "client": "deciduous CLI", "branch": "agent-tests", "is_you": false, "seconds_ago": 29 },
    { "session": "cli:4c3b", "client": "deciduous CLI", "branch": null,          "is_you": false, "seconds_ago": 18 }
  ],
  "active_sessions": 3,
  "window_seconds": 300,
  "branches": [
    { "branch": "agent-tests",
      "last_node": { "node_type": "observation", "title": "Reuse the RFC 7807 shape in fixtures", "change_id": "81c332df-..." },
      "writers": [ ... ] }
  ],
  "branches_total": 3
}
```

What the fields mean, as observed:

- `sessions` is every (session, branch) pair that wrote in the last five minutes, not every running agent. An agent that has only read does not appear.
- `client` is the name the MCP client sent in `initialize` (`docs-work` was the probe client that produced this output); the CLI shows as `deciduous CLI`.
- The CLI's session is named after the repository's root commit (`cli:` plus its first characters), so every clone and worktree of one repository shows as one CLI session. `link` and `status` writes record `branch: null`.
- `branches` lists the latest node on each branch, newest first, writers included, whether or not anyone is writing now. `branches` (the argument) sets how many, default 20; `branches_total` says how many exist.

Nothing in it is a lock. Until 1.0.8 the server took a ten-second lease per (workspace, branch) and refused a second writer; it stopped one-shot clients from writing after themselves and could not stop the CLI, so it was removed. Two sessions writing `agent-api` at the same moment both got `"Node created and linked"`. Every write is atomic on its own; `log_decision`, `capture_conversation_turn` and `close_thread` are each one transaction.

Locks never protected source files either. File ownership is the coordinator's job; an action's `files` list is how one agent shows another what it is about to touch, and `query_nodes` with `file` finds what was decided about a path.

## The message board

Agents ask each other questions and announce interface changes on the board, never in a scratch file. `@label` addresses a message, a reply takes it off the addressee's list, and each agent asks what is waiting for it:

```console
$ deciduous board post --as tests -s "@api is the 422 body stable?" -m "I am asserting code and field, not message. @api confirm the shape."
Posted #222, to api
$ deciduous board read --unanswered api
```

Over MCP the same two operations are `post_message` and `read_messages`, on the same board. Start each agent with its label, `DECIDUOUS_AGENT_LABEL=api claude`, and the hook that `deciduous init` installs shows it what is waiting at session start and on each prompt.

[The message board](board.md) has a full exchange between a CLI and an MCP agent, the rules for what counts as addressed and answered, and the limits.

## Borrowing across branches: took_from

When one agent's node changes another's plan, record the borrow as an edge, not just a sentence. A `took_from` edge runs from the node you took the idea from (any branch) to your node that used it.

MCP, in one call:

```javascript
log_observation({
  workspace: "my-app", branch: "agent-tests",
  title: "Reuse the RFC 7807 shape in fixtures",
  related_to: "32d05bcb-1b2b-4b7b-b3b8-170a8aa8b7fb",
  took_from: "183e9e9a-153a-4141-9fb2-8312fe486012",
  why: "The API side already emits problem+json; fixtures that match it keep the tests honest."
})
```

```json
{ "id": "3c2a5b0b-...", "message": "Observation logged",
  "took_from": { "from_node_id": "183e9e9a-...", "from_change_id": "9ad1b0b7-2c85-4383-b9d9-902411abb3ac", "edge_id": "236548bb-..." } }
```

`took_from` and `related_to` take the server UUID or the full `change_id`. A short prefix is refused: `took_from is not a node id: "9ad1b0b7"`. `add_edge` and `add_node` also take `edge_type: "took_from"`.

CLI, where a `change_id` prefix is enough:

```console
$ deciduous link 17365e54 2b787037 -t took_from -r "Tests use the API agent's 422 contract instead of inventing one"
Created edge 24 (1 -> 24 via took_from)
```

Taking a decision does not make it right in your context. Say in `why` what you checked.

## Watching the workspace live

```console
$ deciduous remote watch --types observation,outcome
Watching: my-app
13:37:11  agent-api  observation "Watch probe observation"
13:37:11  main      outcome     "Watch probe outcome"
```

It prints one line per node write from every writer, MCP and CLI alike; the action written in between was filtered out by `--types`. `--branch` (repeatable) narrows it, `--edges` adds edge events, `--json` prints raw frames. When the connection drops it reconnects with a backoff that starts at one second and doubles to thirty, and asks the server for every event after the last one it saw. Up to 5,000 missed events are replayed; past that the server reports a gap, and you should query the graph. A newly started `remote watch` shows only new writes. `--url` prints a WebSocket URL with the token in its query string, and `--claude-code` prints that URL inside a ready-to-paste Monitor tool call for Claude Code, so keep the output of both out of screenshots and logs.

## What a coordinator still does

Deciduous does not assign tasks, merge branches or run tests. Mark the shared goal `completed` (`close_thread` with `goal_node_id`) only after the branches are integrated and the combined result checked, not when one agent finishes its part.

---

<!-- https://deciduous.dev/content/board.md -->

# Agents message each other on the board

Two agents working at the same time need to ask each other things: is this response shape stable, did you move those fixtures, I am about to change this interface. The message board is where they do it. A message has an id, an author label and the labels it addresses, so "what is waiting for me?" is one query, and a reply is what takes a question off the list.

A shared scratch file does none of that. It has no ids to answer, no way to ask what is addressed to you, two agents editing it conflict, and it is gone with the worktree it was written in.

With a `[remote]` in `.deciduous/config.toml` the board lives on the server, one per workspace, and the CLI and the MCP tools read and write the same one. Without a server it lives in the main checkout's `.deciduous/deciduous.db`, and every git worktree of the repository shares it. The exchange below was run that way on deciduous 1.1.0, in three worktrees of one repository with no server, which is why its ids start at 1.

## An exchange

The tests agent, in its worktree, asks the API agent a question. `@api` in the subject or the body is what addresses it:

```console
$ deciduous board post --as tests -s "@api is the 422 body stable?" \
    -m "I am asserting code and field, not message. @api confirm the shape."
Posted #1, to api
```

The API agent, in a different worktree, asks what is waiting for it:

```console
$ deciduous board read --unanswered api
#1  tests -> api  [agent-tests]  2026-11-13T04:59:01.231529Z
    @api is the 422 body stable?
    | I am asserting code and field, not message. @api confirm the shape.
```

It answers with `--reply-to`. The reply mentions `@tests`, so it is addressed in turn:

```console
$ deciduous board post --as api --reply-to 1 -s "Re: 422 body" \
    -m "Stable: {type, title, errors:[{field, code}]}. @tests codes live in src/errors.ts."
Posted #2 (reply to #1), to tests

$ deciduous board read --unanswered api
Nothing addressed to api is waiting for an answer.
```

Back in the tests worktree, the answer is waiting:

```console
$ deciduous board read --unanswered tests
#2  api -> tests  re #1  [agent-api]  2026-11-13T04:59:01.285198Z
    Re: 422 body
    | Stable: {type, title, errors:[{field, code}]}. @tests codes live in src/errors.ts.
```

A coordinator announces an interface change to both at once:

```console
$ deciduous board post --as lead -s "Interface change: errors are problem+json" \
    -m "@api @tests every 4xx body is RFC 7807 from now on. Reply when your side matches."
Posted #3, to api, tests
```

Message #3 now sits on both agents' unanswered lists, and leaves each list separately. After the tests agent replies, it is still waiting for `api`: (#4 is the probe message quoted under [Labels and mentions](#labels-and-mentions).)

```console
$ deciduous board post --as tests --reply-to 3 -s "Re: problem+json" -m "Fixtures match."
Posted #5 (reply to #3), addressed to nobody (no @label in subject or body)

$ deciduous board read --unanswered api
#3  lead -> api, tests  [main]  2026-11-13T04:59:01.359456Z
    Interface change: errors are problem+json
    | @api @tests every 4xx body is RFC 7807 from now on. Reply when your side matches.
```

That is how a coordinator sees who has not acknowledged a change: `board read --unanswered <label>` for each agent.

## The same board over MCP

An agent connected to the graph server uses two tools, `post_message` and `read_messages`. This exchange was captured on a server, where ids are numbered across every workspace, so they jump:

```javascript
read_messages({workspace: "my-app", unanswered_for: "api"})
```

```json
{ "messages": [{ "id": 222, "author": "tests", "branch": "agent-tests", "mentions": ["api"],
                 "subject": "@api is the 422 body stable?", "reply_to": null, ... }],
  "latest_id": 222, "truncated": false }
```

```javascript
post_message({workspace: "my-app", branch: "agent-api", author: "api",
  subject: "Re: 422 body", reply_to: 222,
  body: "Stable: {type, title, errors:[{field, code}]}. @tests codes live in src/errors.ts."})
```

A person at a terminal and an agent over MCP are on the same board. The reply the agent just posted shows up on the CLI in another checkout:

```console
$ deciduous board read --unanswered tests
#223  api -> tests  re #222  [agent-api]  2026-11-08T18:36:16.277592Z
    Re: 422 body
    | Stable: {type, title, errors:[{field, code}]}. @tests codes live in src/errors.ts.
```

Nobody has to tell an agent the board exists. The instructions the server sends on connect say to coordinate there, never in a scratch file, and to call `read_messages` with `unanswered_for` set to its own label at the start, before touching a file another agent may be changing, and before finishing.

## Labels and mentions

A label is whatever an agent calls itself: `api`, `tests`, `lead`, `A-retrieval`. Nothing registers them, so agree on them before the agents start.

- `@label` anywhere in the subject or the body addresses the message. A message can address several labels, or none.
- A label is at least two characters, starts and ends with a letter or digit, and may contain `_`, `.` and `-`. The full stop in "ask @lead." is not part of the label, and `@a` addresses nobody.
- An address in an email is not a mention. `mail ops@example.com, then @a and @tests.` was posted as `to tests` only.
- `board post` needs to know who is posting: `--as`, or `DECIDUOUS_AGENT_LABEL` in the environment. With neither: `Error: who is posting? Pass --as LABEL (or set DECIDUOUS_AGENT_LABEL).`
- Without `-m`, the body is read from stdin.

## What counts as answered

A message is unanswered for a label when it mentions that label and that label has not posted a reply to it.

- Only a reply (`--reply-to <id>` or `reply_to`) from the addressed label takes it off that label's list. A reply from someone else does not, and neither does a new post that answers it in prose.
- A reply that mentions the asker lands on the asker's list, as #2 did above. A conversation ends when someone replies without a mention.
- Reading a message does not mark it. There is no read state, only replied or not.

## Reading

`board read` prints messages oldest first, with at most twelve lines of each body; `board show <id>` prints one in full.

| CLI | `read_messages` | Returns |
|---|---|---|
| `--unanswered <label>` | `unanswered_for` | What mentions the label and it has not replied to |
| `--to <label>` | `to` | Everything that mentions the label |
| `--from <label>` | `author` | Everything the label posted |
| `--since <id>` | `since_id` | Messages with a greater id |
| `-q, --query <text>` | `query` | Text in the subject or body |
| `--limit <n>` | `limit` | At most n messages: default 50, most 200 |

`--json` prints what `read_messages` returns:

```console
$ deciduous board read --since 2 --json
{
  "messages": [
    {
      "id": 3,
      "branch": "main",
      "author": "lead",
      "subject": "Interface change: errors are problem+json",
      "body": "@api @tests every 4xx body is RFC 7807 from now on. Reply when your side matches.",
      "mentions": [
        "api",
        "tests"
      ],
      "reply_to": null,
      "created_at": "2026-11-13T04:59:01.359456Z"
    }
  ],
  "latest_id": 3,
  "truncated": false
}
```

Keep `latest_id` and pass it as `--since` next time to get only what is new. `truncated: true` means more matched than the limit; read again from `latest_id`.

## Messages that find the agent

Polling is easy to forget, so `deciduous init` installs `.claude/hooks/board-mentions.sh` as a Claude Code SessionStart and UserPromptSubmit hook. When `DECIDUOUS_AGENT_LABEL` is set for the session, the hook puts that label's unanswered messages in front of the agent at start, and anything new on each prompt. Without the variable it does nothing.

Start each agent from its worktree root with its label:

```sh
DECIDUOUS_AGENT_LABEL=api claude
```

What the agent sees, run by hand:

```console
$ DECIDUOUS_AGENT_LABEL=api .claude/hooks/board-mentions.sh start
DECIDUOUS BOARD: messages for @api you have not answered.
Answer each with post_message reply_to=<id>, or: deciduous board post --as api --reply-to <id> -s ... -m ...

#3  lead -> api, tests  [main]  2026-11-13T04:59:01.359456Z
    Interface change: errors are problem+json
    | @api @tests every 4xx body is RFC 7807 from now on. Reply when your side matches.
```

The hook looks for `.deciduous/` in the session's current directory and exits silently when it is not there. It is a file in the repository: a worktree made from a commit that does not include `.claude/hooks/` does not have it. Commit the integration files before making worktrees.

The hook is for Claude Code. An agent in another client has no hook and has to call `read_messages` itself, as the server's instructions tell it to.

## Limits and what the board is not

- A subject is at most 300 characters, a body 64 KB, a label 100 characters. Past that the post is refused: `Error: subject is 301 characters; at most 300 are allowed`.
- `--branch` defaults to the current git branch. It records what the message is about; it does not restrict who can read it.
- Messages are not graph nodes. They are not in `get_graph`, not in `graph.json`, not exported, and `remote pull` does not copy them into the local cache. What two agents settled on the board belongs in the graph as a decision or an observation; the board is how they got there.
- The server board needs server 1.0.9 or newer.
- Anyone holding the server's token can post as any label. A label says who a message claims to be from, not who sent it ([Architecture and trust](architecture.md)).

[Many agents, one graph](teams.md) covers the rest of working in parallel: worktrees, branches, `check_activity` and `took_from`.

---

<!-- https://deciduous.dev/content/recovery.md -->

# Pick up where the last session stopped

A new session starts with nothing but the repository, and the graph on the server holds everything the last one decided. Recovery is reading that graph before writing anything: the goal still open, the decision under it, the last outcome, and anything another agent left on the board for you. An agent does it with the server's MCP tools; a person, or an agent running `/recover`, does it with the CLI after refreshing the local cache.

## What the agent is told

On connect, the server sends its instructions in the MCP `initialize` reply. The part about starting:

```text
At the start of a session, read before writing: `query_nodes` for this branch, `ask_graph` for the topic.
If the work continues an existing goal, attach to it. When a line of work ends: `close_thread`, then
`find_orphans`.
```

So the first calls of a session look like this:

```javascript
query_nodes({workspace: "my-app", type: "goal", status: "active"})
query_nodes({workspace: "my-app", branch: "agent-api", limit: 30})
ask_graph({workspace: "my-app", question: "why did we change the retry deadline?"})
check_activity({workspace: "my-app"})
read_messages({workspace: "my-app", unanswered_for: "api"})
```

`query_nodes` returns summaries, newest first: id, type, status, title, branch, `change_id`, confidence. No descriptions and no rationale. Follow the ids that matter with `show_node`, which adds the description, metadata (prompt, files, commit), documents, and every edge in and out with its rationale.

`ask_graph` finds entry nodes by text and then follows the edges the question asks for: "why" follows choices and revisits, "history" or "pivot" follows revisits and superseded nodes. Each result says how it was reached. For that question it returned the superseded action and decision, the observation that killed them, the revisit and the decision that replaced them, and the goal:

```text
action      superseded  anchor     Apply a 30s deadline to the retry loop
decision    pending     anchor     Per-caller deadline passed in the request context
revisit     pending     anchor     Reconsidering: Use an overall deadline, not an attempt cap
observation pending     anchor     A fixed 30s deadline fails batch jobs that legitimately wait
option      pending     rationale  Cap the attempt count
decision    superseded  anchor     Use an overall deadline, not an attempt cap
goal        active      anchor     Bound retries for failed requests
```

`get_ancestors` from an unfinished action walks back to the decisions and the goal behind it; `get_descendants` from a goal shows everything done under it.

Two traps:

- `add_node` defaults to `pending`. A search for `status: "active"` misses goals nobody activated; query `pending` too before concluding there is no open goal.
- A `superseded` decision is history, not the plan. Look for the revisit after it.

If the work continues an existing goal, attach to it with `parent_id`. Do not log the original request as a second goal with the same title.

## From the CLI: refresh the cache, then read

The CLI reads the local cache, `.deciduous/deciduous.db`, which only knows what this checkout wrote or last pulled. Agents writing over MCP never touch it. Check first:

```console
$ deciduous remote status
...
                 local    server
  nodes              6        23
  edges              6        22

Only on the server (17)
  observation 048e98e6 "The router already parses JSON before handlers run"
  decision 17365e54 "Validate at the HTTP boundary, not after the write"
  ...
Differs: `deciduous remote pull` takes the server's side.
```

`remote status` exits 1 when anything differs. Then:

```console
$ deciduous remote pull
Pulled: my-app <- https://deciduous.example.com
  fetched 23 nodes, 22 edges, 1 deletion(s)
  imported 17 new node(s), updated 0, removed 0; imported 16 edge(s), removed 0
$ deciduous remote status | tail -2
In sync: no writes waiting, and every node, edge and document matches field by field.
Themes and tags are not sent to the server, so they are not compared.
```

`remote pull` first sends anything still waiting in `.deciduous/remote-log.jsonl`, then takes the server's side for every node and edge, including deletions. It does not download document bytes ([Evidence](evidence.md#documents-from-the-cli-reach-the-server)). A fresh clone or a new worktree has an empty cache; `remote pull` is the first thing to run there.

Then read:

```console
$ deciduous nodes --branch "$(git rev-parse --abbrev-ref HEAD)"
$ deciduous show 5ca33b18
$ deciduous narratives pivots
$ deciduous pulse --summary
$ deciduous board read --unanswered api
```

Local ids differ in every checkout. `show`, `link`, `status` and `doc attach` take a `change_id` prefix or the server UUID as well. A prefix only resolves against the cache, so before a pull it fails with advice meant for the no-server mode:

```text
Error: No node has a change_id starting with '5ca33b18'. Run 'deciduous sync' if a teammate created it.
It is not a server id in workspace my-app either.

A node is named by its local id (12, or #12 when digits could also be a change_id prefix), its change_id or a prefix of it (the CHANGE column of `deciduous nodes`, at least 4 hex characters), or, in a project with a [remote], the server's id for it (the `id` MCP tools return) or a prefix of that.
```

A prefix needs only 4 hex characters. With a `[remote]` the fix is `deciduous remote pull`, not `sync`. A server UUID does not get you around the pull. Before it, the CLI recognises the UUID and tells you to pull:

```console
$ deciduous show 14a9f4d8-b37a-...
Error: No node has a change_id starting with '14a9f4d8-b37a-...'. Run 'deciduous sync' if a teammate created it.
It is the server id 14a9f4d8-b37 = change_id 3e460153-12b (Validate create-item requests), which this clone does not have yet. Run `deciduous remote pull` first.
```

After the pull it resolves to the local node:

```console
$ deciduous show 32d05bcb-1b2b-4b7b-b3b8-170a8aa8b7fb
Note: '32d05bcb-1b2b-4b7b-b3b8-170a8aa8b7fb' is the server id 32d05bcb-1b2 = change_id 5ca33b18-c27 (Validate create-item requests): local #11
```

## The /recover command

`deciduous init` writes `.claude/commands/recover.md` to match the project. With a `[remote]` already in `.deciduous/config.toml` (after `remote init` or `remote setup`), the first step is `deciduous remote pull` and `deciduous remote status`, then `nodes`, `nodes --branch`, `edges`, `commands`, `doc list`, the board, and `git status` / `git log`. Without one, you get the git-mode version, which ends with `deciduous sync` instead. If you add `[remote]` after `init`, run `deciduous update` to switch.

Parts of the 1.1.0 template do not work as written:

- `deciduous commands` prints `No commands logged.` in 1.1.0, however many writes the checkout made. Fixed on main (commit ec3ce7a), not in a release yet; the next release logs commands.
- The orphan audit (`deciduous edges | cut -d'>' -f2 ...`) looks for a `>` the tabular `edges` output does not contain, so it flags every node as an orphan: one `CHECK:` line per node, plus one for the table's separator line (`CHECK: ------...`). It also pipes through `awk`, `grep`, `sort` and `cut`, which the template's `allowed-tools: Bash(deciduous:*, git:*, cat:*, tail:*)` does not cover, so Claude Code asks permission to run it. Use `find_orphans` over MCP.
- Step 3, `cat git.log | tail -30`, reads a file nothing creates.
- Its closing section links to `https://notactuallytreyanastasio.github.io/deciduous/` as the "Live graph" and says `PUSH -> Live graph updates`. That is deciduous's own site, not your project's graph.

The template on main adds Step 1.6, which runs `deciduous transcript list` and `deciduous transcript import <session-id>` for sessions the graph does not have yet; 1.1.0 does not ship it, and you can run the import yourself ([Evidence](evidence.md#deriving-the-graph-from-a-transcript)). `deciduous commands` answers on main because of the binary, not the template. Everything else in the list above is unchanged on main: the orphan audit, the `git.log` step and the "Live graph" link are all still there. Delete those lines from your copy of `recover.md`. In a project with a `[remote]`, `deciduous update` then treats the file as yours and leaves it untouched, writing the template it would have used to `.deciduous/update-templates/.claude/commands/recover.md` so you can diff it; you will not get later template fixes without merging them by hand.

## Check the graph against the checkout

The graph says what someone recorded, not what the code is now:

```bash
git status --short
git branch --show-current
git log -5 --oneline
```

Match the branch and commit in the node metadata to the checkout. If an outcome says tests passed and the code has changed since, run them again and record the new result under the same action.

## Leaving a session so the next can recover

The next session reads what you wrote, so end with:

- `close_thread` on each line of work, with the command run and its result, or `success: false` and the error.
- `find_orphans` empty, or each remaining orphan linked to its real cause.
- A reply to every board message addressed to you.
- From the CLI: `deciduous remote status` saying `In sync`. Anything waiting means the server never saw it: `deciduous remote push` sends it.

## When the server is down

CLI writes still succeed locally, exit 0, and say so:

```text
Created node 2 (type: observation, title: written while server down) [branch: main]
Warning: the local write succeeded but the server did not get it: transport error: https://deciduous.example.com/ops: Connection Failed: Connect error: Connection refused (os error 61)
1 write(s) queued in .../.deciduous/remote-log.jsonl. They are sent on the next write, or now with `deciduous remote push` once the server is reachable.
```

`remote status` lists them as `waiting` before it fails on the health check. Once the server answered again, `remote pull` sent the queued write and `remote status` said `In sync`. MCP writes fail outright, since the server is the only place they go. Nothing a teammate cannot see should be described to them as shared. [Operating](operating.md) covers backups and restoring the server; a local `deciduous backup` copies only this machine's cache.

---

<!-- https://deciduous.dev/content/evidence.md -->

# Attach the evidence, or derive the graph from it

A node is only as good as what backs it. Deciduous has two ways to put evidence next to a claim: attach a file to a node with `deciduous doc attach`, which in a project with a `[remote]` uploads the bytes to the server; and `deciduous transcript import`, which reads a Claude Code session's transcript and writes the goals, actions and outcomes it can prove, each marked with what it rests on.

## Say what ran

Before either, the cheapest evidence is a precise outcome: the command, the count, the commit, and what was not checked.

```javascript
close_thread({
  workspace: "my-app", branch: "agent-tests",
  parent_node_id: "<action id>",
  title: "Request validation passes 8 integration cases",
  description: "npm test -- tests/items.test.ts: 8 passed, 0 failed. Browser behaviour not checked.",
  success: true
})
```

"All tests pass" after running one file is the claim the next agent will wrongly rely on. A `files` list and a `commit` on a node are references, not copies: the reader needs the repository to follow them.

## Documents from the CLI reach the server

The server's MCP tools have no upload: 21 tools, none of them attaches a file. Attaching is a CLI command, and agents run it like anyone else.

```console
$ deciduous doc attach 5ee7c7c7 test-output.txt -d "cargo test retry output"
Attached document 1 to node 6 (test-output.txt)
  Description: cargo test retry output
$ deciduous remote status | tail -2
In sync: no writes waiting, and every node, edge and document matches field by field.
Themes and tags are not sent to the server, so they are not compared.
```

The node can be named by local id, `change_id` prefix, or server UUID (`deciduous doc attach de6ccf4c-877b-... file`). The bytes are uploaded to the server, which checks them against their SHA-256, and the attachment is recorded on the node. An agent then sees it in `show_node`:

```json
"documents": [{ "id": "38c69819-818d-4a4f-906c-1e8c6101b889", "filename": "test-output.txt", "mime_type": "text/plain" }]
```

and anyone with the token can download it from `<url>/documents/<id>`, where `<url>` is `url` under `[remote]` in `.deciduous/config.toml`, including any path prefix the server's proxy uses, such as `/deciduous-mcp`:

```console
$ curl -s -i -H "Authorization: Bearer <token>" https://deciduous.example.com/documents/38c69819-818d-4a4f-906c-1e8c6101b889
HTTP/1.1 200 OK
cache-control: no-store, private, max-age=0
content-type: text/plain

test retry ... ok
4 passed; 0 failed
```

Without the token: 401. An unknown id: 404. Behind a Caddy that has only a `handle_path` block ([Run a server](run-a-server.md#3-put-https-in-front-of-it)), leaving out the path prefix gets an empty `200`, not an error. One file can be at most 64 MiB; the server refuses a larger upload with 413. `get_graph` lists the workspace's documents with size, description and node.

Older pages said `doc attach` was local only and that configuring a remote did not upload. That stopped being true; in 1.1.0 the upload happens before the command exits, like every other CLI write.

What does not work in 1.1.0:

- **Documents do not come down.** `deciduous remote pull` in another clone fetched every node and edge and no documents: `deciduous doc list` there said `No documents found.`, and `remote status` in that clone still said "every node, edge and document matches", which was not so. Read other people's attachments with `show_node` and `GET /documents/<id>`.
- **A detached document is still served.** `deciduous doc detach 3` reached the server: the document disappeared from `get_graph`. But `show_node` on its node still listed it, and `GET /documents/<id>` still returned its bytes with 200. If you attached a secret, detaching it does not take it off the server. Whoever runs the server has to delete it from the database: [Remove a document that should never have been attached](operating.md#remove-a-document-that-should-never-have-been-attached).

The token grants access to every workspace on the server, documents included ([Architecture](architecture.md)). Do not attach `.env` files, credential stores, connection strings, or output you have not read.

`deciduous doc describe` reaches the server, like `attach` and `detach`: after `doc describe 1 "second description"`, `get_graph` showed the new description. `doc list`, `doc show`, `doc open` and `doc gc` operate on this checkout's copy in `.deciduous/documents/`.

## Deriving the graph from a transcript

Claude Code writes every prompt, edit, command and result of a session to a JSONL file under `~/.claude/projects/<project>/`. `deciduous transcript import` derives nodes from it: a goal per prompt with the prompt verbatim, actions from edit runs and commits, outcomes from test and build runs with their exit status, and an outcome from the assistant's closing report. Each node carries `metadata.evidence.kind`: `proven` (a tool call and its result) or `inferred` (the assistant said so).

What it cannot derive is an option or a decision. Whether one approach was chosen over another is a judgement about prose, so those still have to be logged as they happen.

Start with the list and a dry run. `transcript list` reads the directory for the current project:

```console
$ deciduous transcript list
/Users/me/.claude/projects/-Users-me-code-my-app
new      6494dc2d    2 prompts  2026-11-08  <session title>
new      305de803    1 prompts  2026-11-05  <session title>

$ deciduous transcript import --dry-run 6494dc2d
Would import <session title> (6494dc2d, 2 prompts)
  goals 2 · actions 11 · outcomes 4 proven, 1 inferred · observations 0 · edges 17
  10 files hashed · 3 subagent runs skipped (their transcripts are separate files) · 15 deciduous MCP writes skipped (already in the graph)
```

It takes a session id (looked up in this project's directory) or a path to a `.jsonl`. The import leaves out every deciduous MCP call the session made, reads such as `query_nodes` included, and every shell command that runs `deciduous`, on the assumption that they already wrote to the graph. It does not check. Imported into a different workspace or server than the session wrote to, or after a write that failed, those records are simply missing; the count still says "already in the graph". Subagents' transcripts are separate files and are not followed. Actions record a hash of each file they touched; `--no-hash` skips that.

In a directory Claude Code has never run in, 1.1.0's `transcript list` fails with the raw `No such file or directory (os error 2)` for the directory it expected (the next release says Claude Code has not run there). Pass `--dir` to `list`; `import` has no `--dir`, so give it the `.jsonl` path.

A real import, into a workspace on the server:

```console
$ deciduous transcript import ~/.claude/projects/<project>/305de803-....jsonl
Imported <session title> (305de803, 1 prompts)
  goals 1 · actions 0 · outcomes 0 proven, 1 inferred · observations 0 · edges 1
  1 deciduous MCP writes skipped (already in the graph)
  root goal #1: deciduous show 1
$ deciduous remote status | tail -2
In sync: no writes waiting, and every node, edge and document matches field by field.
```

The nodes went to the server like any CLI write. On the server, the goal's metadata:

```json
{ "branch": "main",
  "evidence": { "kind": "proven", "source": "transcript", "session": "305de803-...", "uuids": ["fd7edbe1-..."] },
  "session": { "id": "305de803-...", "transcript": "/Users/me/.claude/projects/.../305de803-....jsonl", "turns": 1 } }
```

and the outcome's `evidence.kind` was `inferred`, from the assistant's report at the end of the turn. The nodes keep the transcript's timestamps (`created_at` 2026-11-05 for a session from that day), while `branch` is the current checkout's.

Importing the same transcript again changes nothing:

```text
  goals 0 · actions 0 · outcomes 0 proven, 0 inferred · observations 0 · edges 0
  2 already present · 1 deciduous MCP writes skipped (already in the graph)
```

Read what you are about to share. A goal holds the prompt verbatim and an inferred outcome holds the assistant's report in full; both can contain paths, hostnames and anything pasted into the session, and on a shared server every token holder can read them. Run `--dry-run` first, and import into a workspace whose readers should see that session.

The viewer does not yet show `metadata.evidence`; `deciduous show <id>` prints it (`Evidence: inferred transcript, session 305de803`), and `show_node` returns it in `metadata`.

---

<!-- https://deciduous.dev/content/history.md -->

# Keep the approaches that were abandoned

When an approach turns out wrong, the useful record is not the corrected decision alone but the chain that replaced it: the old decision, the observation that killed it, a `revisit`, and the new decision, with the old one marked `superseded`. The same structure serves history reconstructed after the fact from commits. Both end up in the shared workspace, written either with `deciduous archaeology` from the CLI or node by node over MCP.

```text
old decision --> observation (why it failed) --> revisit --> new decision
  (superseded)
```

## A pivot from the CLI, in one command

`deciduous archaeology pivot` writes the observation, the revisit and the new decision, links them, and supersedes the old node. `--dry-run` shows it first:

```console
$ deciduous archaeology pivot 2465036d \
    "A fixed 30s deadline fails batch jobs that legitimately wait minutes" \
    "Per-caller deadline passed in the request context" \
    -r "One deadline cannot fit interactive and batch callers" -c 75
=== PIVOT CREATED ===

  #6 [observation] "A fixed 30s deadline fails batch jobs that legitimately wait minutes"
    └── linked from #3 "Use an overall deadline, not an attempt cap"
  #7 [revisit] "Reconsidering: Use an overall deadline, not an attempt cap"
    └── linked from #6 [observation]
  #8 [decision] "Per-caller deadline passed in the request context"
    └── linked from #7 [revisit]

  Superseded: #3 "Use an overall deadline, not an attempt cap" -> status: superseded

  Summary: 3 nodes created, 3 edges created, 1 node superseded
```

The first argument takes a local id, `change_id` prefix or server UUID. All of it reached the server; `remote status` afterwards said `In sync`. The new decision is `pending`, like any new node.

The work done under the old decision is history too. `archaeology supersede --cascade` marks a node and everything below it. Run it on the old decision's actions, never on the old decision itself once a pivot hangs under it: the observation, the revisit and the new decision are all below the old decision now, and the cascade follows them. On the old decision, `--dry-run` shows it would take the replacement with it:

```console
$ deciduous archaeology supersede 2465036d --cascade --dry-run
Would supersede node #3 "Use an overall deadline, not an attempt cap"
  Would also supersede (cascade):
    #4 "Apply a 30s deadline to the retry loop"
    #6 "A fixed 30s deadline fails batch jobs that legitimately wait minutes"
    #5 "Retry loop stops at the deadline"
    #7 "Reconsidering: Use an overall deadline, not an attempt cap"
    #8 "Per-caller deadline passed in the request context"
  Total: 6 node(s) would be marked superseded
```

On the action under it, only the work is marked:

```console
$ deciduous archaeology supersede 04e9c57d --cascade
Superseded node #4 "Apply a 30s deadline to the retry loop"
  Also superseded (cascade):
    #5 "Retry loop stops at the deadline"
  Total: 2 node(s) marked superseded
```

Always run `--dry-run` first and read the list before running the real thing.

## The same pivot over MCP

The server has no pivot tool. Three `add_node` calls with `parent_id`, then `update_node`:

```javascript
add_node({workspace: "my-app", branch: "agent-api", node_type: "observation",
  title: "Mobile client cannot parse problem+json",
  description: "iOS 1.x hard-codes {error: string}; 12% of traffic",
  parent_id: "<old decision id>"})
add_node({workspace: "my-app", branch: "agent-api", node_type: "revisit",
  title: "Reconsidering the error format", parent_id: "<observation id>"})
add_node({workspace: "my-app", branch: "agent-api", node_type: "decision",
  title: "problem+json for v2 clients, legacy body for v1", parent_id: "<revisit id>"})
update_node({workspace: "my-app", branch: "agent-api", node_id: "<old decision id>", status: "superseded"})
```

Each call needs the id the previous one returned, so they cannot go in one batch. The CLI reads it back as a pivot once pulled (the six new nodes here are the `log_decision` that made the old decision and its two options, plus the three above):

```console
$ deciduous remote pull
Pulled: my-app <- https://deciduous.example.com
  fetched 14 nodes, 12 edges, 0 deletion(s)
  imported 6 new node(s), updated 0, removed 0; imported 5 edge(s), removed 0
$ deciduous narratives pivots -b agent-api
=== PIVOTS === (1 found)

Pivot #1: [revisit #9] "Reconsidering the error format"
  Old approach: #13 [decision] "Use RFC 7807 problem+json over an ad-hoc error object" (superseded)
  Triggered by: #11 [observation] "Mobile client cannot parse problem+json"
  New approach: #14 [decision] "problem+json for v2 clients, legacy body for v1"
```

`ask_graph` follows revisits and superseded nodes when the question uses a history word (`changed`, `pivot`, `history`, `previously`, `replaced` and the like; `change` is not one). "How has the retry deadline changed?" takes that route and comes back with both the dead decision and its replacement. "Why did we change the retry deadline?" goes by the rationale route instead, because of `why` ([Recovery](recovery.md#what-the-agent-is-told)).

## Statuses

`superseded` means replaced by a newer approach; `abandoned` means tried and dropped with nothing replacing it. `deciduous status <id> superseded` and `abandoned` both work, although 1.1.0's `status --help` lists only `pending, active, completed, rejected`. Over MCP, `update_node` takes all six.

`active` is only set when someone sets it: new nodes are `pending`, and so is the new decision `archaeology pivot` writes. So `query_nodes` with `status: "active"` returns only what someone explicitly activated: the goals and actions in [Record the reasoning](workflow.md) are, decisions from `log_decision` are `completed`, and a pivot's new decision is `pending`. It can return `{"count":0,"nodes":[]}` in a workspace with a current decision. For the current state, query with no status filter and drop `superseded`, `abandoned` and `rejected` nodes, or use `consolidation_report`, which treats any decision not in those three as current. For the history, use no filter; for the pivots, `type: "revisit"`.

## Reconstructing history from commits

For a codebase that was built before anyone logged decisions, the graph can be filled in from git. Pick one bounded question (why retries have a cap, why an endpoint has two response shapes) rather than the whole repository, and read the evidence first:

```bash
git log --oneline -- src/retry.rs
git show <sha> -- src/retry.rs
```

A commit proves what changed, not why. Record the author's stated reason as such, mark your inference as inference, and say what you did not look at. Record options only where the evidence shows they were considered; alternatives you can think of now are not history.

The CLI can backdate a node and tie it to the commit:

```console
$ deciduous add decision "Retry with exponential backoff (historical)" \
    -d "Reconstructed from commit message" --date 2024-03-01 --commit <sha>
Created node 9 (type: decision, ...) [commit: 64551157...] [branch: main] [date: 2024-03-01T00:00:00-05:00]
```

The date reaches the server: `query_nodes` returned `"created_at": "2024-03-01T05:00:00.000000Z"` for it. `--date` takes `YYYY-MM-DD`, `YYYY-MM-DD HH:MM:SS` or RFC 3339, read in local time. MCP's `add_node` has no date argument; an agent reconstructing history puts the date and full hash in the description, or uses the CLI. (An older page said a backdated CLI node stays local. With a `[remote]` it does not.)

`deciduous archaeology timeline` lists nodes in creation order, so backdated ones sort where they belong:

```console
$ deciduous archaeology timeline -b main
=== TIMELINE === (9 nodes)

  2024-03-01  #9   [decision]      Retry with exponential backoff (historical) pending
  2026-11-08  #1   [goal]          Bound retries for failed requests        pending       90%
  2026-11-08  #3   [decision]      Use an overall deadline, not an attempt cap superseded    80%
  2026-11-08  #4   [action]        Apply a 30s deadline to the retry loop   superseded
  2026-11-08  #6   [observation]   A fixed 30s deadline fails batch jobs that legitimately wait minutes pending
  2026-11-08  #7   [revisit]       Reconsidering: Use an overall deadline, not an attempt cap pending
  2026-11-08  #8   [decision]      Per-caller deadline passed in the request context pending       75%
```

It reads the local cache; `remote pull` first. `-t` filters by type, `-l` limits to the most recent N, `--json` for scripts.

## Narratives

A narrative is the prose version: how one part of the system got the way it is, with its pivots. `deciduous narratives init` writes `.deciduous/narratives.md` with one section per goal that is not superseded or abandoned (pending and completed goals included) to fill in:

```console
$ deciduous narratives init
Created .../.deciduous/narratives.md with 1 goal section(s)
$ deciduous narratives show
# Narratives
...
## Bound retries for failed requests
> Node #1 | Status: pending

**Current state:** [How it works today]

**Evolution:**
1. [First approach] - [why]
2. **PIVOT:** [what changed] - [why it changed]
3. [Current approach] - [why this is better]
```

That file is local. It is not sent to the server, and the `.gitignore` that `deciduous init` writes ignores everything in `.deciduous/` except `config.toml` and `graph.json`, so git does not carry it either. Teammates see the graph, not the narrative; put anything they need into nodes, or commit the file somewhere outside `.deciduous/` with `-o`.

## The commands and skills init installs

`deciduous init` writes `.claude/commands/decision-graph.md` (`/decision-graph`: build a graph from commit history, with narratives as the source of truth and commits as evidence) and three instruction files, `.claude/skills/pulse.md`, `narratives.md` and `archaeology.md`, for mapping the current design, writing narratives, and turning them into nodes. 

Only `/decision-graph` is a slash command. Claude Code loads project skills from `.claude/skills/<name>/SKILL.md` ([Claude Code docs](https://code.claude.com/docs/en/skills)); init writes flat `.md` files with no frontmatter, so there is no `/pulse`, `/narratives` or `/archaeology`, although the generated `CLAUDE.md` lists them as skills. Point an agent at them by path: "read `.claude/skills/archaeology.md` and follow it".

All of them drive the CLI (`deciduous add`, `link`, `status`, `--date`), so in a project with a `[remote]` what they write reaches the server. Review them before handing them to an agent: `/decision-graph` assumes the binary is at `~/.cargo/bin/deciduous`.

## Check the result

`find_orphans` finds nodes nothing points at; an empty list says the graph is connected, not that it is true. Have a second agent check the important claims against the commits they cite.

---

<!-- https://deciduous.dev/content/operating.md -->

# Backups, upgrades, tokens

There are two things to look after: the PostgreSQL database and the `.env` file next to it. The server itself holds no state, so if you rebuild it from the same `.env` against the same database, the graph comes back. Every command on this page was run against a v1.1.0 Docker install on 2026-11-08, with the output shown, except where a section says otherwise.

Run the commands from the directory that holds the install's `.env` and `compose.yaml`. A Docker install the CLI made (`remote setup --docker-postgres` on a developer machine) keeps them apart: the settings are in `~/.config/deciduous/server/.env` and the compose files in `~/.config/deciduous/server/bundle-1.1.0/deciduous-mcp-docker/`. Run the commands from that bundle directory and add `--env-file ~/.config/deciduous/server/.env` to each `docker compose` command. Each CLI version unpacks its own `bundle-<version>` directory, so the number in the path is the version of the CLI that last ran setup. A private database CA for that install goes in that bundle directory's `certs/`. If your machine has `docker-compose` rather than the `docker compose` plugin, use that; the arguments are the same.

## Back up

For the bundled PostgreSQL:

```bash
umask 077
docker compose -f compose.yaml -f compose.local.yaml exec -T db \
  pg_dump -U deciduous -d deciduous --format=custom > deciduous-$(date +%F).dump
```

The dump includes document contents (`document_blobs`), not only the graph. Copy it off the VM, together with `.env`. Without the token in `.env`, a restored server is one that no existing client can log in to.

For a managed database, use your provider's backups or `pg_dump` against `DATABASE_URL`.

## Prove the backup restores

A backup has not been tested until it has been restored. Restore it into a throwaway PostgreSQL with no network access, held in memory:

```bash
docker run -d --name deciduous-restore-check --network none \
  -e POSTGRES_USER=deciduous -e POSTGRES_DB=postgres \
  -e POSTGRES_HOST_AUTH_METHOD=trust \
  --tmpfs /var/lib/postgresql/data postgres:17.11-alpine
until docker exec deciduous-restore-check pg_isready -h 127.0.0.1 -U deciduous -d postgres; do sleep 1; done

docker exec -i deciduous-restore-check pg_restore -U deciduous \
  --create --exit-on-error --dbname=postgres < deciduous-2026-11-08.dump
docker exec deciduous-restore-check psql -X -U deciduous -d deciduous -tA \
  -c 'SELECT count(*) FROM decision_nodes;' -c 'SHOW random_page_cost;'
docker rm -f deciduous-restore-check
```

Use `-h 127.0.0.1` in the wait. Over the Unix socket, `pg_isready` already reports the image's temporary initialisation server as ready, which shuts down a moment later; a restore started then fails with `terminating connection due to administrator command`. The temporary server does not listen on TCP, so the TCP check waits for the real one.

The test install printed `3` and `1.1`: three nodes, and the database's planner setting. Use `--create`. Without it, the restore lands in a database that already exists and skips the database-level settings the migrations made, even though the migration ledger says they ran.

## Upgrade the server

[Take a backup](#back-up) first. Putting the old binary back does not undo a migration, so rolling back means restoring the pre-upgrade dump.

Extract the new release bundle into a new directory next to the one [Run a server](run-a-server.md) created (`deciduous-mcp-docker`). Copy your `.env` into it, plus `certs/` if you use a private database CA, and run setup there. From the directory that holds `deciduous-mcp-docker`, as the user who owns it:

```bash
mkdir deciduous-mcp-1.2.0
tar -xzf deciduous-mcp-docker.tar.gz -C deciduous-mcp-1.2.0 --strip-components=1
cp -p deciduous-mcp-docker/.env deciduous-mcp-1.2.0/
cd deciduous-mcp-1.2.0 && ./scripts/setup.sh
```

Keep `COMPOSE_PROJECT_NAME` the same: it is how setup finds the running containers and the PostgreSQL volume. The new server runs pending migrations before it listens, and setup waits for `/ready`.

Rerunning setup on the same release was tested and took 8 seconds, because the image was already built. Settings, volume and graph all survived. A real version change was not run for this page; the procedure is the one in `deciduous_mcp/DEPLOY.md`.

## Upgrade the CLI

People upgrade their own CLI however they installed it (`brew upgrade deciduous`, `cargo install deciduous`, or a release binary). The CLI and server versions do not have to match: a 1.1.0 CLI works against the 1.0.12 reference server. After upgrading, run `deciduous update` in each repository. It refreshes the Claude Code, OpenCode and Windsurf files that `init` wrote, for whichever of `.claude/`, `.opencode/` and `.windsurf/` the repository has. It upgrades a server only when that server is a native one on the same machine; a Docker install on a VM is never touched.

## Rotate the token

For a Docker install made by hand, set a new token in `.env` and rerun setup. These commands are for the Linux VM; on macOS, `sed -i` needs `''` after it. Keep the single quotes around the value, as `setup.sh` writes it: tools that read the token back out of `.env`, including the one-liner in `deciduous_mcp/DEPLOY.md`, expect them.

```bash
NEW=$(openssl rand -hex 32)
sed -i "s/^DECIDUOUS_MCP_TOKEN=.*/DECIDUOUS_MCP_TOKEN='$NEW'/" .env
./scripts/setup.sh
```

For the other two kinds of install (not run for this page):

- A native server the CLI installed: edit `DECIDUOUS_MCP_TOKEN` in `~/.config/deciduous/server/.env`, then restart it with `launchctl kickstart -k gui/$(id -u)/dev.deciduous.server` on macOS or `systemctl --user restart deciduous-server.service` on Linux. The CLI on that machine reuses the token in `~/.config/deciduous/credentials`, so store the new one there too with `deciduous remote login --url http://127.0.0.1:<port>`, which checks the new token against the restarted server before storing it.
- A Docker install the CLI made: edit the same `.env`, then rerun its setup with `DECIDUOUS_ENV_FILE=~/.config/deciduous/server/.env ~/.config/deciduous/server/bundle-1.1.0/deciduous-mcp-docker/scripts/setup.sh`, and `deciduous remote login --url http://127.0.0.1:<port>` as above.

Once it restarts, the old token gets 401 and the new one works. Rotation logs out every client at once, but most commands do not say so. `remote status`, `remote pull`, `remote push` and `remote watch` fail and exit 1:

```
Error: reached https://deciduous.example.com but the server rejected the token (401). Check DECIDUOUS_MCP_TOKEN.
```

(`pull` and `push` print it without the `reached <url> but` part.) A write succeeds locally and warns, as below. Reads of the local cache, such as `deciduous nodes`, print nothing and exit 0.

Each person stores the new token with `deciduous remote login --url <base>`. They also need to update the `Authorization` header in their agent's MCP registration (see [Connect your agents](clients.md)), which `remote login` does not touch. A CLI write made with a rejected token is not lost. It is saved locally, queued, and the command still exits 0 after printing this warning:

```
Warning: the local write succeeded but the server refused it: the server rejected the token (401). Check DECIDUOUS_MCP_TOKEN.
1 write(s) wait in /home/you/my-app/.deciduous/remote-log.jsonl, and every later write will be refused the same way until that is fixed. `deciduous remote status` lists them.
```

Once the new token is stored, the next write sends the queued one along with it. `deciduous remote push` sends the queue on its own. Because the exit code is 0, a script cannot tell that the write never reached the server unless it also runs `deciduous remote status`, which exits 1 while anything is waiting.

## Remove a document that should never have been attached

`deciduous doc detach` does not take a document off the server. In 1.1.0 the detached document no longer appears in `get_graph`, but `show_node` still lists it and `GET /documents/<id>` still returns its bytes. To remove a leaked file, delete it from the database. Documents are addressed by the SHA-256 of their contents, so hash the same file:

```bash
HASH=$(sha256sum leaked.env | cut -d' ' -f1)
docker compose -f compose.yaml -f compose.local.yaml exec -T db \
  psql -X -U deciduous -d deciduous -v ON_ERROR_STOP=1 -v h="$HASH" <<'EOF'
BEGIN;
DELETE FROM node_documents WHERE content_hash = :'h';
DELETE FROM document_blobs WHERE content_hash = :'h';
COMMIT;
EOF
```

On the test install, `GET /documents/<hash>` went from 200 to 404, and the attacher's `remote status` still reported in sync. This deletes the bytes from every workspace that attached the same file, which is what you want for a secret. Two copies remain that the database cannot reach: the attacher's `.deciduous/documents/`, and every backup taken since the file was attached. Rotate the secret itself as well.

## Remove a node's text for good

Deleting a node does not remove its text either. `deciduous delete` and `delete_node` set `deleted_at` on the row: the title, description and prompt stay in `decision_nodes`, and the write is also recorded, title included, in `graph_events`, the log `remote watch` replays from. After `deciduous delete` on a node whose description held a pasted secret, both tables still had it. To purge it, take the node's server id (`id` from `show_node`, or `deciduous show` once pulled) and delete both:

```bash
docker compose -f compose.yaml -f compose.local.yaml exec -T db \
  psql -X -U deciduous -d deciduous -v ON_ERROR_STOP=1 -v id=<server id> <<'EOF'
BEGIN;
DELETE FROM graph_events WHERE payload->>'id' = :'id';
DELETE FROM decision_nodes WHERE id = :'id';
COMMIT;
EOF
```

Its edges go with it. On the test install that printed `DELETE 2` and `DELETE 1`, a `pg_dump --data-only` no longer contained the text, and the deleting clone's `remote status` still said `In sync`. Every clone that pulled before the delete still has the node's text in its `.deciduous/deciduous.db`, and backups keep it too.

## Watch what is happening

```bash
docker compose -f compose.yaml -f compose.local.yaml ps
docker compose -f compose.yaml -f compose.local.yaml logs --tail=100 server
```

For an external database, leave out `-f compose.local.yaml`. `/health` returns 200 whenever the process is running. `/ready` also checks the database and migrations, and returns 503 until both are fine; point uptime checks at `/ready`.

From any client, `deciduous remote watch` prints one line for each node write to that project's workspace as it lands, from every agent and every CLI. Edge writes are shown only with `--edges`:

```
Watching: my-app
13:45:15  main      action      "Written while watching"
```

## When a client and the server disagree

`deciduous remote status` compares one repository's local cache with its workspace on the server. It exits 1 when there is any difference. It also exits 0, printing `Local only`, in a project with no `[remote]`, so a script should check for the `In sync` line as well:

```
                 local    server
  nodes              3         3
  edges              0         0

In sync: no writes waiting, and every node, edge and document matches field by field.
Themes and tags are not sent to the server, so they are not compared.
```

`deciduous remote pull` sends anything waiting, then refreshes the cache from the server. That is the fix for "only on the server". `deciduous remote push` resends queued writes after an outage. Its repair flags (`--seed`, `--repair`, `--overwrite-server`, `--drop-rejected`, `--retry-rejected`, `--drop <op>`, `--overwrite`) are for a cache that has drifted in ways no queued write explains. Read `deciduous remote push --help` before using them: `--overwrite` replaces the server's copy of every row with yours. Common cases are listed in [Troubleshooting](troubleshooting.md).

## Stop or remove

`docker compose ... down` stops the install and keeps the database volume. `down --volumes` deletes the database. Do not run it unless that is what you want and you have a dump you have restored.

---

<!-- https://deciduous.dev/content/local.md -->

# Without a shared server

There are two fallbacks for when nobody runs a server you can join. `deciduous remote setup --local` runs the same server on your own machine as a background service, so the CLI and your agents work exactly as they would against a team server, with one person writing. `DECIDUOUS_NO_SERVER=1 deciduous init` skips the server entirely and shares the graph through a git-tracked `.deciduous/graph.json`. Use the first if you might join a team later; use the second only when a running service is not an option.

## A server on this machine

`remote setup --local` looks for a server this machine already has, and installs one if there is none.

> **On Linux, 1.1.0's `--local` does not finish on its own.** With apt's PostgreSQL it needs a role with a password and `--database-url`, and the systemd unit it writes is refused until one line is edited; both are under [What a fresh install does](#what-a-fresh-install-does). The fix for the unit is PR #330, not yet released. `remote setup --docker-postgres` avoids both.

 On a machine that has one, it reuses it and changes nothing about it:

```text
$ deciduous remote setup --local
deciduous remote setup
Every project writes its decision graph to a shared server. This connects /home/you/code/my-app
to one: a server on this machine, or one someone else runs.

   Found local server at http://127.0.0.1:4000
   Wrote .deciduous/config.toml [remote] url = http://127.0.0.1:4000
   Connected http://127.0.0.1:4000 holds 0 nodes, 0 edges in workspace my-app
   Unchanged Claude Code already has a deciduous MCP server

Done: this project writes to http://127.0.0.1:4000. Restart Claude Code so it picks up the server;
it sends the logging instructions when it connects.
```

"This machine has a server" means `~/.config/deciduous/server/.env` exists. That settings file is authoritative once written: every later `--local`, in every project, points at the server it describes. The flags that choose how a new server is built do not replace an existing one. `--docker` on a machine with a native server is refused:

```text
Error: this machine's server is already set up to run as a background service (/Users/you/.config/deciduous/server/.env), and it is kept that way. To replace it, stop it and move that file away first; its database is not touched.
```

and `--database-url` against the same native server is accepted but ignored, with one line saying so: `Using the server already set up in ~/.config/deciduous/server/.env; its database and port stand`.

The `Unchanged Claude Code already has a deciduous MCP server` line deserves a second look. `remote setup` registers its server with Claude Code at user scope only when `claude mcp get deciduous`, run in the project, finds no `deciduous` server in any scope: user, the project's `.mcp.json` (even one still waiting for approval), or local. If one is found, it is left alone even when it points somewhere else, and the "Restart Claude Code" advice below it will not fix that. Check with `claude mcp get deciduous`; the [Claude Code section of Connect your agents](clients.md) has the fix.

### What a fresh install does

The output above was observed on a machine that already had a server. The steps below were run on Linux (debian:12 with systemd 252 and PostgreSQL 15 from apt, deciduous 1.1.0) and checked against `src/server.rs` and `src/local_server.rs`; the macOS service step was read, not run.

| Flag | Server runs as | Database |
| --- | --- | --- |
| `--local` (nothing else) | the release's single-file `deciduous-mcp` executable, as a user service | PostgreSQL on `localhost:5432` as `$USER`, no password, database `deciduous`. Works with Homebrew's PostgreSQL, which trusts localhost. Not with apt's: see below |
| `--database-url <url>` | the same user service | the PostgreSQL you name |
| `--docker` | a container from the release's `deciduous-mcp-docker.tar.gz` | the PostgreSQL from the first two rows; `localhost` is rewritten to `host.docker.internal`. On Linux that is the Docker gateway, where PostgreSQL does not listen out of the box: set `listen_addresses` and add a `pg_hba.conf` line for `172.16.0.0/12`, or use `--docker-postgres` |
| `--docker-postgres` | a container (implies `--docker`) | a new PostgreSQL 17 container |
| `--port <port>` | any of the above | used only on first setup. Without it, `DECIDUOUS_PORT` from the environment is used; failing that, a terminal asks (suggesting a free port in 20000-32767), and without a terminal a free port is chosen and printed (`Chose port N`) |

With no flags and a terminal, `remote setup` asks the same questions as a menu. Without a terminal and without `--local` or `--url`, it stops and prints the four scripted forms.

**Debian and Ubuntu: `--local` alone fails.** The CLI's hint for a machine without PostgreSQL is `sudo apt install postgresql`, but that package's `pg_hba.conf` requires a password for TCP to `127.0.0.1` (`host all all 127.0.0.1/32 scram-sha-256`), the CLI connects over TCP with no password, and nothing creates a `$USER` role. Even with the role, the failure is the client's, not PostgreSQL's:

```text
Preparing postgres://you@localhost:5432/deciduous ...
Error: cannot connect to you@localhost:5432/deciduous: key :password not found in: [ parameters: [], ... username: "you", database: "deciduous", port: 5432, sync_connect: true ]
```

Give the role a password and name it in the URL:

```bash
sudo -u postgres createuser --createdb --pwprompt $USER
deciduous remote setup --database-url postgres://$USER:<password>@localhost:5432/deciduous
```

On debian:12 that created the database and got as far as the service step, which fails in 1.1.0 for the reason below.

Before any of the steps, setup checks for a service manager. On Linux without a `systemctl --user` session (a container, WSL without systemd, a login without a user bus) it prints `Note systemd user services are not available here ...`, offers Docker if there is a terminal, and otherwise still installs the executable, prepares the database and writes `.env`, then stops with the command to run the server in the foreground and rerun setup.

The native install, in order:

1. Downloads `deciduous-mcp-<os>-<arch>` for the CLI's own version, checks it against the release's `checksums.txt`, and installs it as `~/.config/deciduous/server/bin/deciduous-mcp`.
2. Picks the bearer token. If the machine already has one (`DECIDUOUS_MCP_TOKEN`, else `~/.config/deciduous/credentials`) of at least 32 bytes, that becomes the server's token; otherwise 64 random hex digits.
3. Runs the executable once with `DECIDUOUS_MCP_COMMAND=prepare-database`: it connects, creates the database if missing (the role needs `CREATEDB`), migrates, and exits. A refusal usually comes back in PostgreSQL's words (`role "x" does not exist`, `password authentication failed`). Two exceptions were seen on Linux:
   - No password in the URL against a server that wants one gives the `key :password not found` keyword list above.
   - On a machine where another user ran the server executable first, it prints only `Error: error: AccessDenied`, because the executable unpacks `/tmp/libc-musl-<hash>.so` owned by that user and a second user cannot replace it (moving the file away fixed it).

   If nothing listens on 5432 at all, setup finds that out before step 1, before downloading anything, and says so, printing `brew install postgresql@17 && brew services start postgresql@17` / `sudo apt install postgresql`.
4. Writes `~/.config/deciduous/server/.env`, mode 600. This machine's file has these keys (values other than the secrets shown):

   ```text
   DECIDUOUS_SERVER_MODE=native
   DECIDUOUS_SERVER_VERSION=1.1.0
   DECIDUOUS_BIND_ADDRESS=127.0.0.1
   DECIDUOUS_PORT=4000
   DECIDUOUS_MCP_TOKEN='<token>'
   DATABASE_URL='<ecto url>'
   DB_SSL=false
   DB_SSL_VERIFY=full
   DB_SSL_CA_FILE=
   POOL_SIZE=10
   DECIDUOUS_PREPARE_DATABASE=true
   ```

5. Installs a user service that starts at login and restarts on exit (**on Linux this fails in 1.1.0**; see below): a LaunchAgent `dev.deciduous.server` at `~/Library/LaunchAgents/dev.deciduous.server.plist` on macOS, a systemd user unit `deciduous-server.service` on Linux. The service definition carries only paths; the token and database URL stay in `.env`, which the server reads itself through `DECIDUOUS_ENV_FILE`. Output goes to `~/.config/deciduous/server/logs/server.log`. On Linux, user services stop at logout unless you run `loginctl enable-linger $USER`.
6. Waits for `/ready`, then stores the token in `~/.config/deciduous/credentials` if it differs from the one there, writes `[remote]`, and registers with Claude Code as above. Without Claude Code on `PATH` it prints `Note Claude Code not found; register the server in your client: http://127.0.0.1:<port>/mcp` instead.

**Linux: the service does not start in 1.1.0, or on main.** The unit file the CLI writes puts `WorkingDirectory` in double quotes, and systemd refuses the whole unit. Fixed by [PR #330](https://github.com/notactuallytreyanastasio/deciduous/pull/330), not yet merged or released as of 2026-11-08. Setup stops after writing `.env`:

```text
Error: `systemctl --user restart deciduous-server.service` failed: Failed to restart deciduous-server.service: Unit deciduous-server.service has a bad unit file setting.
```

`systemd-analyze verify` (systemd 252) says why:

```text
/home/you/.config/systemd/user/deciduous-server.service:8: WorkingDirectory= path is not absolute: "/home/you/.config/deciduous/server"
deciduous-server.service: Unit configuration has fatal error, unit will not be started.
Unit deciduous-server.service has a bad unit file setting.
```

Until that is fixed, remove the quotes from that one line, start the service, and run setup again to finish connecting the project:

```bash
sed -i 's/^WorkingDirectory="\(.*\)"$/WorkingDirectory=\1/' ~/.config/systemd/user/deciduous-server.service
systemctl --user daemon-reload && systemctl --user restart deciduous-server.service
deciduous remote setup --local
```

Setup stopped before step 6, so without the last line the project has no `[remote]`, no stored token and no Claude Code entry. Run again, it finds the running server (`Found local server at http://127.0.0.1:<port>`), stores the token and writes `[remote]`. Checked on debian:12: before the edit `systemd-analyze verify` refuses the unit, after it the unit verifies clean. The quoted `ExecStart=` and `Environment=` lines are fine. macOS (launchd) is not affected.

The edit does not last. Whenever the server is not answering (after a logout without linger, or `systemctl --user stop`), the next `remote setup --local` in any project prints `Starting the server at ..., which is not answering`, rewrites the unit with the quotes, and fails the same way. Repeat the `sed` and the restart.

The server binds `127.0.0.1` because `DECIDUOUS_BIND_ADDRESS` says so; a server started by hand without that setting listens on every interface. Every start re-runs the migrations (`DECIDUOUS_PREPARE_DATABASE=true`), and `deciduous update` in a project that writes to this server replaces an older executable and restarts the service. Docker installs are not upgraded by `update`.

A database URL may carry `?sslmode=`. The CLI maps it onto the server's TLS settings: `require` → `DB_SSL=true DB_SSL_VERIFY=none`, `verify-ca` → `ca`, `verify-full` → `full`. `disable`, `allow` and `prefer` all turn TLS off; `prefer` does not mean "try TLS" here. Any other query parameter is refused rather than dropped. The meaning of each mode is on [Architecture](architecture.md#tls-to-postgresql).

The first log lines after a start say what the server is doing. From this machine's `server.log`:

```text
[info] Database TLS: off (DB_SSL unset or false)
[info] Events.Listener: listening on graph_events
[info] Running DeciduousMcp.Web.Router with Bandit 1.13.1 at 127.0.0.1:4000 (http)
```

To remove a native install (from `DEPLOY.md`; the database is left in PostgreSQL):

```bash
launchctl bootout gui/$(id -u)/dev.deciduous.server      # macOS
rm ~/Library/LaunchAgents/dev.deciduous.server.plist
systemctl --user disable --now deciduous-server.service  # Linux
rm ~/.config/systemd/user/deciduous-server.service && systemctl --user daemon-reload
rm -r ~/.config/deciduous/server
```

`DEPLOY.md` leaves out the unit file; `disable` only removes its `WantedBy` link, and `systemctl --user` keeps listing the unit until the file is gone. The stored token in `~/.config/deciduous/credentials` and each project's `[remote]` also stay behind.

### One token per machine

The CLI keeps exactly one stored token, in `~/.config/deciduous/credentials`, not one per server URL. If you write to a local server for some projects and to a team server for others, only one of them can use the stored token. Two things replace it without asking:

- `deciduous remote login --url https://deciduous.example.com` stores the team token over the local one.
- `deciduous remote setup --local` stores the local server's token over whatever is there, whenever they differ.

The other server's projects then fail on every write. The write itself still succeeds locally and the command exits 0; the op waits in the log:

```text
Created node 6 (type: observation, title: written with the other server's token) [branch: main]
Warning: the local write succeeded but the server refused it: the server rejected the token (401). Check DECIDUOUS_MCP_TOKEN.
1 write(s) wait in /home/you/code/my-app/.deciduous/remote-log.jsonl, and every later write will be refused the same way until that is fixed. `deciduous remote status` lists them.
```

`DECIDUOUS_MCP_TOKEN` is read before the stored file, so the working arrangement is: store the token you use most, and export the other one in the environment of the projects that need it (a per-directory env tool such as direnv, or a wrapper script). Once the right token is in place, `deciduous remote push` sends what waited.

The ordering also matters the first time. A brand-new local server adopts whatever token the machine already holds (step 2 above), so installing a local server after `remote login` to a team server gives the local server the team's token. Both then accept the same secret, and rotating the team token later breaks the local server's projects too. Run `remote setup --local` with `DECIDUOUS_MCP_TOKEN` unset and the credentials file empty if you want the two kept apart. (This ordering was read from `machine_token()` in `src/server.rs`, not run.)

Claude Code has the same shape of problem: one user-scope `deciduous` entry. For a second server, register it at local scope in the repositories that use it, or in a project `.mcp.json`, which needs `DECIDUOUS_MCP_TOKEN` exported where `claude` starts; see [Connect your agents](clients.md).

## No server at all

`deciduous init` does not complete without a server. In a terminal it asks; without one it writes its files (`.claude/`, `CLAUDE.md`, `.gitignore`, `.github/` and the rest), then prints the four `remote setup` forms and exits 1. To opt out, say so:

```text
$ DECIDUOUS_NO_SERVER=1 deciduous init
   Creating .gitignore (track .deciduous/graph.json, ignore the database)
   Creating .gitattributes (merge the graph file record by record, fold it in PR diffs)
   Configured git merge driver for graph records
   Creating .deciduous/graph.json (run `deciduous sync` to fill it, then commit it)
   ...
   Skipped shared graph server (DECIDUOUS_NO_SERVER is set)
```

The ignore rules keep the database private and track two files:

```text
# .gitignore
.deciduous/*
!.deciduous/config.toml
!.deciduous/graph.json

# .gitattributes
.deciduous/graph.json merge=deciduous linguist-generated=true
```

and the merge driver goes into `.git/config`, which git never shares:

```text
merge.deciduous.name deciduous decision graph record
merge.deciduous.driver deciduous merge-record %O %A %B
```

Every write goes to the local database and is mirrored into `graph.json` at once. Each write also says where it went, so nobody mistakes this mode for a shared one:

```text
Note: written to /home/you/code/my-app/.deciduous/deciduous.db only; this project has no shared server. `deciduous remote setup` connects one.
```

### Two clones, one graph

This was run with a bare origin and two clones, `a` and `b`. In `a`: add a goal, `deciduous sync`, commit `.gitignore .gitattributes .deciduous/config.toml .deciduous/graph.json` by name, push. A fresh clone `b` sees the goal immediately (the database follows `graph.json` on the next command), but its `.git/config` has no merge driver until something registers it. `deciduous sync` does:

```text
$ deciduous sync
Configured git merge driver for the graph file (this clone)
Synced /home/you/code/b/.deciduous/graph.json (1 nodes, 0 edges, 0 themes, 0 tags on disk)
  Database and records already agree
```

Then both clones changed the graph at once. `a` added an option, linked it, and set the goal `active`; `b` added a different option, linked it, and replaced the goal's prompt. Both committed; `a` pushed; `b` pulled:

```text
$ git pull --no-edit origin HEAD
Merge made by the 'ort' strategy.
 .deciduous/graph.json | 24 +++++++++++++++++++++++-
$ deciduous nodes
ID    CHANGE    TYPE         STATUS     TITLE
1     94e4b9f7  goal         active     Shared goal
3     d04a258b  option       pending    Option from A
2     01ed84dd  option       pending    Option from B
```

No conflict markers, both new options and both edges, and node 1 carries `a`'s status and `b`'s prompt. The driver merges record by record, and a record both sides changed field by field, breaking ties on `updated_at`. Deletes are tombstones, so a delete reaches clones that already had the node. A file that does end up with conflict markers (merged in a clone with no driver registered) is repaired by the next `deciduous sync`.

The routine:

```bash
git pull
deciduous sync          # takes in what the pull brought, registers the driver if missing
deciduous sync --check  # before pushing: reports what sync would change, writes nothing
git add .deciduous/graph.json
```

`sync --help` says `--check` exits 1 when anything is pending, and the `CLAUDE.md` that init writes tells agents the same (`deciduous sync --check    # what is pending? (exit 1 if anything)`). It exits 0 with changes pending, on 1.1.0 and on main. With the database edited behind the file it printed `Changes would: 1 nodes updated from records` or `Changes would: 1 nodes set back to graph.json's version`, depending on how the row was edited, and exited 0 both times. Read its output rather than relying on the exit status in a hook. Ordinary writes are mirrored into the file as they happen, so in day-to-day use there is rarely anything pending.

Numeric ids are per clone (`b` numbered "Option from B" 2, `a` numbered "Option from A" 2). Refer to nodes across machines by change_id prefix: `deciduous link 94e4b9f7 01ed84dd`.

What this mode does not have: an MCP server over HTTP, `check_activity`, live `remote watch`, and anything faster than a git push. Agents can write through `deciduous mcp`, the stdio server, against the local database, but init registers it with no client (it writes no `.mcp.json`). For Claude Code, in the project:

```text
$ claude mcp add --transport stdio --scope project deciduous -- deciduous mcp
Added stdio MCP server deciduous with command: deciduous mcp to project config
$ cat .mcp.json
{
  "mcpServers": {
    "deciduous": {
      "type": "stdio",
      "command": "deciduous",
      "args": [
        "mcp"
      ],
      "env": {}
    }
  }
}
```

(Claude Code 2.1.319; the format is on [Claude Code's MCP page](https://code.claude.com/docs/en/mcp).) The stdio tools are not the server's. They take local ids, link with `link_nodes`, and `add_node` has no `parent_id`, although the generated `CLAUDE.md` says "create and link in one call: `add_node` with `parent_id`". The stdio server answers that with `add_node has no argument "parent_id". Its arguments are: branch, commit, confidence, description, files, node_type, prompt, title`. See [MCP tools](mcp.md). `graph.json` also carries every prompt and description you write, so treat it like any other committed file.

### Moving to a server later

Point the project at a server with `deciduous remote init https://deciduous.example.com --workspace my-app` (or `remote setup --url`, or `--local`). If you registered the stdio server above, remove it first (`claude mcp remove deciduous -s project`, and commit the `.mcp.json` change): while any server called `deciduous` is registered, `remote setup` prints `Unchanged` and leaves it, and `remote init` registers nothing with Claude Code at all. The history written before the project had a remote goes up with it. From a clone of the two-clone repository above, pointed at an empty workspace:

```text
$ deciduous remote init http://127.0.0.1:4000 --workspace docsref-seed2
Remote: http://127.0.0.1:4000
  workspace: docsref-seed2
  claim: claimed (by this repository's root commit)
  server holds 0 nodes, 0 edges, 0 documents
  sent 2 local node(s), 1 edge(s) the server lacked
```

`deciduous remote status` then says In sync. If it ever lists rows as "only here" that no op covers, `deciduous remote push --seed` sends them; it adds what the server lacks and never changes a row the server already has. [Operating a server](operating.md) covers the other push flags. Once a project has a `[remote]`, `deciduous sync` is no longer the step that shares anything.

`graph.json` does not go away. Every write is still mirrored into it, the ignore rules still track it, and `deciduous sync` still syncs it. Commit `.deciduous/config.toml` so teammates' clones pick up the `[remote]`. A teammate who wrote nodes before pulling it has rows the server never got and no op to send them; `remote push` says `Nothing to push`, and `remote status` names the fix:

```text
Only here (1)
  action b4b791a1 "A wrote before pulling"  (no op covers it: `deciduous remote push --seed`)
$ deciduous remote push --seed
Seeded: my-app -> http://127.0.0.1:4000
  nodes 1 of 1
  edges 0 of 0
```

Once every clone has the `[remote]`, the server is the shared copy and committing `graph.json` only duplicates it. To stop, drop `!.deciduous/graph.json` from `.gitignore` and `git rm --cached .deciduous/graph.json`.

---

<!-- https://deciduous.dev/content/troubleshooting.md -->

# Troubleshooting

Most problems are one of four things: the CLI and the agent are talking to different servers, the token in use belongs to a different server, the workspace name collides with another repository, or the server was unreachable and writes are waiting. Each entry below starts from the text deciduous 1.1.0 prints. Every entry was captured by provoking it, except where the entry says otherwise.

Two commands answer most questions:

```bash
deciduous remote status      # this copy vs the server: waiting writes, rejected writes, rows that differ
claude mcp get deciduous | grep -E 'Status|URL|Scope'   # where Claude Code's agent is actually writing
```

Unfiltered, `claude mcp get` prints the whole token. `remote status` exits 0 when it prints `In sync` or `Local only`; anything waiting, rejected or different exits 1.

## Setting up

### `init` stops with "no terminal to ask"

```text
Error: /home/you/code/my-app has no server configured ([remote] in .deciduous/config.toml), and there is no terminal to ask where its graph should live. Choose one:

    deciduous remote setup --local                  # this machine: a background service, PostgreSQL on localhost:5432
    deciduous remote setup --database-url <url>     # this machine's server, a PostgreSQL you name
    deciduous remote setup --docker-postgres        # this machine: PostgreSQL and the server in Docker
    deciduous remote setup --url <url>              # a server someone else runs

then rerun this command. Tests and CI in a throwaway directory can set DECIDUOUS_NO_SERVER=1.
```

**Cause.** `init` was run from a script, an agent's shell, or anything else without a terminal on stdin, in a project with no `[remote]`. It exits 1, but it has already written `.claude/`, `CLAUDE.md`, `.deciduous/`, `.gitignore`, `.gitattributes` and `.github/workflows/cleanup-decision-graphs.yml` before stopping, so the directory looks initialized.

**Fix.** Run the `remote setup` form that fits, then `deciduous init` again. To join a team server: `deciduous remote login --url https://deciduous.example.com` once per machine (it reads the token from stdin), then `deciduous remote setup --url https://deciduous.example.com`. `DECIDUOUS_NO_SERVER=1 deciduous init` is not a way past this error: it makes a project with no server at all, sharing its graph through git (see [Without a shared server](local.md#no-server-at-all)).

### "the server rejected the token (401)"

```text
Error: reached https://deciduous.example.com but the server rejected the token (401). Check DECIDUOUS_MCP_TOKEN.

Nothing was stored or written.
```

`remote init` words it slightly differently: `Error: the server rejected the token (401). Check DECIDUOUS_MCP_TOKEN.` followed by `Nothing was written; the project is unchanged.` Both exit 1 and change nothing.

**Causes**, in the order worth checking:

1. **The URL ends in `/mcp`.** The CLI wants the base URL; the agent wants `<base>/mcp`. Given `.../mcp`, the CLI asks for `.../mcp/health`, which is behind authentication, and reports a token problem that is really a path problem:

   ```text
   Error: cannot reach http://127.0.0.1:4000/mcp: the server rejected the token (401). Check DECIDUOUS_MCP_TOKEN.
   ```

   Drop the `/mcp`.
2. **A stale `DECIDUOUS_MCP_TOKEN` in this shell.** The environment wins over the stored token. `env | grep DECIDUOUS_MCP_TOKEN`, then `unset` it or correct it.
3. **The stored token belongs to another server.** There is one stored token per machine, not one per URL. The message says "Check DECIDUOUS_MCP_TOKEN" even when the token came from `~/.config/deciduous/credentials`. See [One token per machine](local.md#one-token-per-machine).
4. **The token is wrong.** Ask whoever runs the server. (`remote login --url` also says "Check DECIDUOUS_MCP_TOKEN" when the bad token came from stdin.) `deciduous remote login --url https://deciduous.example.com` reads a token from stdin, checks it against that server, and only then stores it (mode 0600).

### "cannot reach ... Connection refused"

```text
Error: cannot reach http://127.0.0.1:9: transport error: http://127.0.0.1:9/health: Connection Failed: Connect error: Connection refused (os error 61)
```

Nothing listens at that address and port. For a team server, check the URL with whoever runs it and `curl https://deciduous.example.com/health` (it answers `ok` without a token). For this machine's server, the port is `DECIDUOUS_PORT` in `~/.config/deciduous/server/.env` and the log is `~/.config/deciduous/server/logs/server.log`.

A name that does not resolve fails the same way, with `Dns Failed: resolve dns name 'deciduous.invalid:443': failed to lookup address information`.

### "no such endpoint (404)"

```text
Error: cannot reach http://127.0.0.1:4000/deciduous-mcp: no such endpoint (404). Is the URL right, including any path prefix?
```

The host answered but not at that path. A server behind a reverse proxy usually lives under a prefix (for example `https://deciduous.example.com/deciduous-mcp`); a server reached directly has none. The base URL is the one where `curl <base>/health` prints the body `ok`. An empty 200 does not count.

### "the server's response was not a graph" / "was not a claim"

```text
Error: reached https://example.com but the server's response was not a graph: Failed to read JSON: EOF while parsing a value at line 1 column 0
```

`remote init` prints `the server's response was not a claim: ...` with the same JSON error. This is the same mistake as the 404 above, a missing path prefix, behind a proxy that answers unknown paths with an empty 200 instead of a 404. Caddy does this with only a `handle_path` block. Fix the URL, and give the proxy a catch-all 404 ([Run a server](run-a-server.md#3-put-https-in-front-of-it)).

### "timed out reading response"

The CLI gives `/health` 15 seconds. A server that is up but slow to answer (one production server took 2-7 s per `/health` on 2026-11-08) can push `remote setup --url` over that, and it fails with `timed out reading response` before anything is stored. Run it again. If it keeps happening, the proxy or the server is struggling; `curl -w '%{time_total}\n' https://deciduous.example.com/health` shows by how much.

### "no token for the shared graph"

```text
Error: no token for the shared graph.

Store one (kept outside every repository, mode 0600):

    deciduous remote login

or set DECIDUOUS_MCP_TOKEN for a one-off.
```

Neither `DECIDUOUS_MCP_TOKEN` nor `~/.config/deciduous/credentials` holds a token. `remote setup --url` says the same in one line and exits 1:

```text
Error: no token: set DECIDUOUS_MCP_TOKEN or run `deciduous remote login --url http://127.0.0.1:4000` first
```

Use `deciduous remote login --url <base>`, as that line says, not the plain `deciduous remote login` the longer message suggests. With `--url` a wrong token is refused (`... the server rejected the token (401) ... Nothing was stored.`); without it, whatever comes in on stdin is stored (`Token: stored in ~/.config/deciduous/credentials`) unchecked, and the mistake shows up on the next write. Note also that `remote setup --url` with a token only in the environment does not store it: the next shell without the variable gets this message.

### "key :password not found" (Linux, `--local`)

```text
Error: cannot connect to you@localhost:5432/deciduous: key :password not found in: [ parameters: [], ... username: "you", database: "deciduous", port: 5432, sync_connect: true ]
```

`remote setup --local` against Debian's or Ubuntu's PostgreSQL, which wants a password on `127.0.0.1` while the CLI sends none. Create a role with a password and pass `--database-url`; see [Without a shared server](local.md#a-server-on-this-machine).

### "bad unit file setting" (Linux, 1.1.0)

```text
Error: `systemctl --user restart deciduous-server.service` failed: Failed to restart deciduous-server.service: Unit deciduous-server.service has a bad unit file setting.
```

The systemd unit 1.1.0 writes quotes `WorkingDirectory`, which systemd refuses. Not fixed in any release yet (PR #330 is open). The `sed` workaround, and the rerun of `remote setup --local` that has to follow it, are on [Without a shared server](local.md#a-server-on-this-machine).

### "invalid workspace name"

```text
Error: the server returned 422: invalid workspace name "a/b": it looks like a path; pass the repo root's basename
```

Workspace names are one path segment. The server trims and lowercases them (`--workspace "My App"` is stored as `my app`), so two spellings that differ only in case are one workspace.

## Writing

### "the local write succeeded but the server did not get it"

```text
Created node 1 (type: goal, title: Written while the server is down) [confidence: 70%] [branch: main]
Warning: the local write succeeded but the server did not get it: transport error: http://127.0.0.1:9/ops: Connection Failed: Connect error: Connection refused (os error 61)
1 write(s) queued in /home/you/code/my-app/.deciduous/remote-log.jsonl. They are sent on the next write, or now with `deciduous remote push` once the server is reachable.
```

**Cause.** The server was unreachable (or took longer than the 10 seconds a write waits for it). Nothing is lost: the write is in the local database and the op is in `.deciduous/remote-log.jsonl`. The command exits 0.

**What to do.** Usually nothing. The next CLI write that reaches the server sends everything queued before it. To see what is waiting:

```text
$ deciduous remote status
Log: 3 write(s) waiting, 0 rejected  (/home/you/code/my-app/.deciduous/remote-log.jsonl)
  waiting   f7b164cd  create goal f50e03ed "Written while the server is down"
  waiting   87b844eb  create action 316bf956 "Second"
  waiting   d8aa0105  link f50e03ed -> 316bf956 (leads_to)
Error: cannot reach http://127.0.0.1:9: ...
```

`remote push` while the server is still down exits 1 and keeps everything (`3 write(s) still waiting in ...`). Once it is back:

```text
$ deciduous remote push
Pushed 3 op(s) to my-app: 3 applied, 0 already there, 0 rejected
```

Pushing twice is safe; the server applies each op at most once, by its id, and reports repeats as "already there". For a server that is up but slow, `DECIDUOUS_OPS_TIMEOUT=<seconds>` raises the 120-second limit on each `remote push` request.

### "the server refused it: the server rejected the token (401)"

```text
Warning: the local write succeeded but the server refused it: the server rejected the token (401). Check DECIDUOUS_MCP_TOKEN.
1 write(s) wait in /home/you/code/my-app/.deciduous/remote-log.jsonl, and every later write will be refused the same way until that is fixed. `deciduous remote status` lists them.
```

The project's server is up but the token in use is not its token: almost always the one-token-per-machine problem after `remote login` or `remote setup --local` for a different server. The write exits 0, so a script will not notice. Put the right token in place ([One token per machine](local.md#one-token-per-machine)), then `deciduous remote push`.

### "belongs to another repository"

```text
Warning: the local write succeeded but the server refused it: workspace "p5" on http://127.0.0.1:4000 belongs to another repository: an unrelated project whose directory is also called p5 (the name is the directory name, lowercased) claimed it first, and this repository shares none of its root commits.

Give this project its own workspace:

    deciduous remote init http://127.0.0.1:4000 --workspace <another-name>

or, if the two repositories really should write one graph, say so by naming it:

    deciduous remote init http://127.0.0.1:4000 --workspace p5
```

**Cause.** The default workspace is the repository's directory name. The server ties a workspace to the root commits of the first repository that writes to it, and refuses one that shares none. Two unrelated projects both called `api` collide here; two clones or worktrees of one repository never do.

**Fix.** Pick a distinct name with `--workspace`. `remote init` with the new name sends what waited (`sent 1 local node(s), 0 edge(s) the server lacked`); `remote status` confirms with `In sync`. Naming an existing workspace explicitly is how you say two repositories should share it: `remote init` then reports `claim: adopted`.

A repository with no commit yet cannot be tied to anything. `remote init` warns, and writes wait in the log until the first commit:

```text
  note: this repository has no commit yet, so the server cannot tie workspace "my-app" to it, and an unrelated repository also called my-app could later claim the workspace with these writes in it. Nothing is sent until the first commit; the writes wait in the log, and the first command after that commit sends them.
```

"The first command" is not quite right: after the first commit, reads (`nodes`, `show`) and `remote status` send nothing, and status still shows `Log: 1 write(s) waiting`. The next write, or `deciduous remote push`, sends them.

### Rejected writes

`remote status` lists ops the server refused (as opposed to ops it never received) with the server's reason. They stay in the log until you decide: `deciduous remote push --retry-rejected` after fixing the cause, `--drop-rejected` to discard them all, or `--drop <op-id prefix>` for one. None was provoked for this page; the flags are from `remote push --help`.

### "Local only: no remote configured"

```text
$ deciduous remote status
Local only: no remote configured for this project.

    deciduous remote init <url>
```

`status` exits 0 here; `push`, `pull` and `watch` print `Error: no remote configured for this project.` and exit 1. The project was initialized with `DECIDUOUS_NO_SERVER=1`, or `.deciduous/config.toml` lost its `[remote]` table. A linked git worktree with no `[remote]` of its own uses its main checkout's.

## CLI and agent disagree

### The agent's nodes are not in `deciduous nodes`, or yours are not in the agent's

First, `claude mcp get deciduous | grep -E 'Status|URL|Scope'`, and compare its URL with `[remote] url` in `.deciduous/config.toml`:

```text
$ claude mcp get deciduous
deciduous:
  Scope: User config (available in all your projects)
  Status: ✔ Connected
  Type: http
  URL: https://deciduous.example.com/deciduous-mcp/mcp
  Headers:
    Authorization: Bearer <token>
```

That is from a machine whose projects point at `http://127.0.0.1:4000`: CLI writes go to one server, the agent's to another, and both report success. `remote setup` does not fix this. It registers Claude Code only when no `deciduous` server is registered, and otherwise prints `Unchanged Claude Code already has a deciduous MCP server` whatever URL that one has. Re-register it yourself, or give the repository its own `.mcp.json`; both are on [Connect your agents](clients.md).

Second, if the URLs agree: CLI reads (`nodes`, `show`, `serve`) come from the local database, which is a cache. It does not refresh itself. After an agent writes over MCP:

```text
$ deciduous remote status
                 local    server
  nodes              1         2

Only on the server (1)
  observation 96096527 "MCP probe obs"

Differs: `deciduous remote pull` takes the server's side.
$ deciduous remote pull
Pulled: my-app <- http://127.0.0.1:4000
  fetched 2 nodes, 0 edges, 0 deletion(s)
  imported 1 new node(s), updated 0, removed 0; imported 0 edge(s), removed 0
```

Third, the workspace. An agent passes `workspace` on each call; a `.mcp.json` may pin one with `X-Deciduous-Workspace`, and a pinned header overrides the argument. `list_workspaces` over MCP shows every name on the server; two near-identical names are usually the split.

### "No node has a change_id starting with ... Run 'deciduous sync'"

```text
Error: No node has a change_id starting with '3bcdac84'. Run 'deciduous sync' if a teammate created it.
It is the server id 3bcdac84-4e0 = change_id 11111111-222 (idempotent), which this clone does not have yet. Run `deciduous remote pull` first.

A node is named by its local id (12, or #12 ...), its change_id or a prefix of it ..., or, in a project with a [remote], the server's id for it ... or a prefix of that.
```

The first line is wrong for a project with a server: `sync` is the no-server command and does nothing for this. The second line is right. An agent created the node over MCP and the local cache has not seen it; `deciduous remote pull`, then the same `link` works (`Note: '3bcdac84' is the server id ... local #7`).

### Themes and tags are missing on the server

They are never sent. `remote status` says so on every run: `Themes and tags are not sent to the server, so they are not compared.`

## MCP over HTTP

These are what an MCP client (or `curl`) sees from `<base>/mcp`.

| Response | Meaning |
| --- | --- |
| `401 {"error":"unauthorized"}` | No `Authorization: Bearer <token>` header, or the wrong token. |
| `404` with `"message":"Session not found"` and `"detail":"This session expired or the server restarted. Send a new initialize request without a session id to start another."` | The session id is unknown: the server restarted, the session idled out, or the client never sent `notifications/initialized` after `initialize` (a session that skips it is dropped, and the next call gets this). Reconnect the MCP server in the client. |
| `405` on `GET /mcp` | Expected. The server offers no server-to-client stream; everything is POST. |
| `query_nodes has no argument "bogus". Its arguments are: branch, file, limit, search, status, type, workspace` | Every tool refuses an argument it does not have and names the ones it does. Usually an agent using a stdio tool name or argument against the HTTP server; see [MCP tools](mcp.md). |
| `node_id is not a node id: "11111111"` | Server tools take the full server UUID (`id` in every result). The CLI's 8-character change_id prefixes do not work over MCP. |

## Reporting a problem

Include `deciduous --version`, the server version (`serverInfo.version` in the MCP `initialize` reply), the command, and the error text as printed. Replace tokens with `<token>`. Two outputs carry one: `claude mcp get deciduous`, unfiltered, prints `Authorization: Bearer` followed by the full token (Claude Code 2.1.319), and `deciduous remote watch --url`, which you may have open, prints a URL with the token in its query string. Edit the first as in the sample above; never paste the second.

---

<!-- https://deciduous.dev/content/concepts.md -->

# Graph concepts

A deciduous graph is typed nodes joined by typed, directed edges, kept per workspace (one per repository) on a shared server. Seven node types, seven edge types, six statuses, and a confidence from 0 to 100. Every node has two identities: a server UUID that MCP tools use, and a change_id that survives every copy and every machine. The CLI and the server reject anything outside these lists, by name.

## Node types

| Type | Records |
| --- | --- |
| `goal` | What someone asked for. Carries the request verbatim in `prompt`. The only node that may have no parent. |
| `option` | One way to do it, considered before choosing. |
| `decision` | The choice between options. A useful title names what it beat. |
| `action` | Code or config changed to carry out a decision. |
| `outcome` | What happened: the test count, the error, the number. |
| `observation` | A fact learned along the way that matters to the plan. Attaches anywhere. |
| `revisit` | An earlier choice being reconsidered: links the old decision, the observation that undid it, and the new decision. |

The flow has two shapes, depending on how the decision was written. Built node by node (`deciduous add`, `add_node`), it is `goal -> option -> decision -> action -> outcome` with `leads_to` edges. Built with MCP's `log_decision`, the decision comes first and its options hang under it: `goal -> decision -> option`, with a `chosen` or `rejected` edge from the decision to each option. Do not then link the options back to the decision; the server refuses an edge that reverses an existing one (see [Edge types](#edge-types)). Observations attach where they were learned. The graph does not enforce either order; `find_orphans` (MCP) reports any non-goal node with no incoming edge, which is the usual sign of a missing link.

1.1.0's `add --help` leaves `revisit` out of its list; it is accepted, and the next release lists it. Anything outside the list is refused:

```text
Error: unknown node type 'bogus'; expected one of: goal, decision, option, action, outcome, observation, revisit
```

The server's `query_nodes` also accepts `feedback`, a legacy type kept so old imported graphs stay readable. New nodes cannot be created with it. Likewise the status `done`: old graphs carry it, so imports and `query_nodes` accept it, but no write sets it (`add_node` with `status: "done"` answers `status must be one of pending, active, completed, rejected, superseded, abandoned; got "done"; nothing was written`). Read it as `completed`.

## Edge types

An edge runs from one node to another in the same workspace. The two may be on different branches. The server refuses an edge that already exists, and an edge whose reverse exists, because two nodes cannot be each other's parent; `took_from` is exempt from both. After `log_decision`, linking the chosen option back to its decision gets:

```text
bb3060b2-... -> 45a3019e-... (chosen) already exists; 45a3019e-... -> bb3060b2-... would make the two nodes each other's parent, and nothing was written. A decision's options hang under it with chosen/rejected edges (decision -> option); to put a decision under its goal, link goal -> decision.
```

| Type | From -> to |
| --- | --- |
| `leads_to` | The default: parent to child along the flow. |
| `chosen` | Decision to the option it took. |
| `rejected` | Decision to an option it turned down. |
| `requires` | A node to something it depends on. |
| `blocks` | A node to something it prevents. |
| `enables` | A node to something it makes possible. |
| `took_from` | The node an idea came from, to the node that reused it. Usually across branches, between agents. |

`log_decision` draws `chosen` and `rejected` edges from the decision to its options; `log_observation` with `took_from` draws the edge from the source to the new observation. From the CLI: `deciduous link <from> <to> -t took_from -r "why"`.

## Status

`pending` (the default), `active`, `completed`, `rejected`, `superseded`, `abandoned`. Nothing sets `active` on its own: new nodes are `pending` until someone changes them. 1.1.0's `status --help` lists only the first four; all six are accepted, and the next release lists them all. Anything else is refused:

```text
$ deciduous status 1 done
Error: unknown status 'done'; expected one of: pending, active, completed, rejected, superseded, abandoned
```

`superseded` is for a decision that was right once and has been replaced (`deciduous archaeology supersede` sets it, with `--cascade` for descendants); `abandoned` is for something tried and dropped. Both keep the node, which is the point: the graph is most useful about the paths not taken. Deleting a node (`deciduous delete`, MCP `delete_node`) is a soft delete on the server.

## Confidence

An integer from 0 to 100, set by whoever wrote the node. It is a judgement, not a measurement. The CLI refuses anything outside the range:

```text
error: invalid value '150' for '--confidence <CONFIDENCE>': 150 is not in 0..=100
```

## Identity: id, change_id, local number

| Identity | Looks like | Where it works |
| --- | --- | --- |
| Server `id` | `8889e255-4305-4fc5-a4f2-d316db4e316e` | Every MCP tool that takes `node_id`, `parent_id`, `from_node_id`, `to_node_id`. The CLI accepts it too. |
| `change_id` | `96096527-2046-4a39-863a-7e67c3cf194e` | The same on every machine, in `graph.json`, and on the server. The CLI accepts a prefix (`deciduous link 5e906850 96096527`); `deciduous nodes` prints the first 8 characters in the CHANGE column. Over MCP, `log_observation`'s `took_from` and `related_to` accept a full change_id; `show_node` does not. |
| Local number | `1`, `2`, `3` | One machine's database only. Two machines number the same node differently. |

MCP tools do not accept prefixes: `show_node` with `"11111111"` answers `node_id is not a node id: "11111111"`.

A change_id also makes a write safe to retry. `add_node` with a `change_id` the workspace already holds, for a node of the same type and title, returns that node with `created: false` instead of making a second one. The same change_id with a different title is refused:

```text
change_id 11111111-2222-4333-8444-555555555555 is already node 3bcdac84-4e0d-410f-890f-d1f8f32712a4, action "idempotent"; this call names a action "different". Nothing was written. Use another change_id, or update_node to change that node.
```

## Workspace

A workspace is one repository's graph on a server. Its name comes from `workspace` under `[remote]` in `.deciduous/config.toml`, which `remote init` and `remote setup` write: by default the repository's root directory name, lowercased (`Docs_Ref_Upper` becomes `docs_ref_upper`), or whatever `--workspace` says. The server trims and lowercases names and refuses anything that looks like a path.

The first repository to claim a workspace holds it by its root commit ids. `remote init` claims at once; after `remote setup`, the next `remote status`, `remote pull` or write does. Clones and worktrees of that repository share the root commit and are let in; an unrelated repository with the same directory name is refused until it picks another name or names this one explicitly (see [Troubleshooting](troubleshooting.md#belongs-to-another-repository)).

Over MCP, the workspace for a call is decided in this order: the `X-Deciduous-Workspace` header if the client sends one, then the call's `workspace` argument, then `scratch`. Tools that name a node by id (`show_node`, `get_ancestors`, `get_descendants`, `update_node`, `delete_node`, `delete_edge`) act in that node's workspace instead; a header that pins a different workspace makes them refuse. Read tools also accept `workspace: "*"` for every workspace at once; writes refuse it. A workspace is a name for routing, not a permission: anyone holding the server's token can read and write all of them. See [Architecture](architecture.md#the-trust-boundary).

## Branch

Every node records the git branch it was written on, in its metadata. The CLI detects it (`--branch` overrides, `--no-branch` skips); MCP clients pass `branch` on each write, because the server cannot see the agent's checkout. Branch is for filtering (`deciduous nodes -b feature-x`, `query_nodes` with `branch`) and for `check_activity`'s view of who is writing where. Nothing is locked by branch: two agents on one branch both write, and their nodes interleave.

---

<!-- https://deciduous.dev/content/reference.md -->

# CLI reference

The `deciduous` commands people actually use, grouped by what you are trying to do, with flags as `deciduous <command> --help` prints them in 1.1.0. In a project connected to a server (one whose `.deciduous/config.toml` has a `[remote]` table), every write command writes the local database, queues a record of the change (an op) in `.deciduous/remote-log.jsonl`, and sends it to the server before it exits; every read command reads the local database, which is a cache refreshed by `remote pull`. Commands marked **server** need a `[remote]`; commands marked **no server** only matter without one.

Anywhere a command takes a node, it accepts a local number or a change_id prefix. In a project with a `[remote]` it also accepts a server UUID, once the node is in the local cache.

Any deciduous command run where no `.deciduous` exists in the current directory or above it creates `.deciduous/deciduous.db` in the current directory and exits 0: `deciduous nodes` in an empty directory does this. From then on that directory is a project, and it captures every repository below it that has no `.deciduous` of its own, worktrees included: their writes go to that file, not to their own server. Delete a stray `.deciduous` when you find one.

## Connect a project to a server

### `remote setup` (server)

Connect this project to a shared graph server, step by step. In a terminal it asks; flags answer for scripts. Ends by writing `[remote]`, storing the token if needed, and registering Claude Code (only if Claude Code has no `deciduous` server yet).

There is no `--workspace` flag: setup names the workspace after the project's directory and does not claim it for this repository; the next `remote status`, `remote pull` or write does. If another repository with the same directory name runs `remote init` first, it takes the name, and every write from this project is refused with `belongs to another repository`. To choose the name, or to claim it at once, use `remote init <URL> --workspace my-app` (below).

The Claude Code registration runs `claude mcp add --scope user --transport http deciduous <URL>/mcp --header "Authorization: Bearer <token>"`, so the token is stored in plain text in `~/.claude.json`. If a `deciduous` server is already registered, even one pointing at a different server, setup prints `Claude Code already has a deciduous MCP server` and leaves it; to switch servers, run `claude mcp remove deciduous -s user` first.

| Flag | Meaning |
| --- | --- |
| `--url <URL>` | Use the server at this URL (token from `DECIDUOUS_MCP_TOKEN` or the stored one). The usual choice. |
| `--local` | Use this machine's server; set it up if there is none. See [Without a shared server](local.md). |
| `--port <PORT>` | Port for this machine's server, first setup only. |
| `--database-url <URL>` | PostgreSQL for this machine's server; `?sslmode=require\|verify-ca\|verify-full` for TLS. The environment's `DATABASE_URL` is never used unless passed here. |
| `--docker` | Run this machine's server in Docker. |
| `--docker-postgres` | Also run a new PostgreSQL in Docker (implies `--docker`). |

```text
$ DECIDUOUS_MCP_TOKEN=<token> deciduous remote setup --url https://deciduous.example.com
```

A token given only through the environment is checked but not stored.

### `remote login` / `remote logout`

`login [--url <URL>]` reads a token from stdin and stores it in `~/.config/deciduous/credentials` (mode 0600; `$XDG_CONFIG_HOME/deciduous/credentials` if that is set). With `--url` it checks the token against that server first and stores nothing if the server refuses it. `logout` deletes the stored token. There is one stored token per machine; see [One token per machine](local.md#one-token-per-machine).

### `remote init <URL>` (server)

Point this project at a server without the wizard: checks `/health` and the token, claims the workspace for this repository, sends any local history the server lacks, writes `[remote]`. Does not touch Claude Code.

| Flag | Meaning |
| --- | --- |
| `--workspace <NAME>` | Workspace name. Defaults to the git repository's root directory name. Naming an existing workspace explicitly lets this repository share it. |

```text
$ deciduous remote init http://127.0.0.1:4000 --workspace my-app
Remote: http://127.0.0.1:4000
  workspace: my-app
  claim: claimed (by this repository's root commit)
  server holds 0 nodes, 0 edges, 0 documents

Written to .deciduous/config.toml. The token stays in ~/.config/deciduous/credentials (or DECIDUOUS_MCP_TOKEN), never here.
```

The message names `~/.config` even when `XDG_CONFIG_HOME` has moved the file.

### `remote adopt [ROOT] --url <URL>` (server)

Walk a directory for projects that already have a `.deciduous` and point each at the server. Existing configuration is left alone. `-n, --dry-run` shows what would change, but in 1.1.0 it is not free of side effects: like any command run outside a project (see the top of this page), it creates `.deciduous/deciduous.db` in ROOT, and then lists ROOT itself as a project to configure, under workspace `scratch`:

```text
$ deciduous remote adopt --url http://127.0.0.1:4000 -n
Would configure: 2 projects under .

  scratch  (.)                                 would configure
  p1                                           would configure

2 would be configured, 0 left alone
```

Delete `ROOT/.deciduous` after a dry run.

## Check and repair the connection

### `remote status` (server)

How far the local copy has drifted from the server: ops waiting and rejected, node and edge counts, and every row that differs, field by field. Exits 0 on `In sync`, and on `Local only: no remote configured for this project.`; anything waiting, rejected or different exits 1.

```text
Remote: http://127.0.0.1:4000
Workspace: my-app
Log: 0 write(s) waiting, 0 rejected  (/home/you/code/my-app/.deciduous/remote-log.jsonl)

                 local    server
  nodes              2         2
  edges              1         1

In sync: no writes waiting, and every node, edge and document matches field by field.
Themes and tags are not sent to the server, so they are not compared.
```

### `remote push` (server)

Send the ops waiting in `.deciduous/remote-log.jsonl`, in order. The server applies each at most once, so pushing twice is safe. Normally unnecessary: every write sends what is waiting.

| Flag | Meaning |
| --- | --- |
| `--retry-rejected` | Send rejected ops again, after fixing the cause. |
| `--drop-rejected` | Discard the ops the server rejected (read why with `remote status` first). |
| `--drop <OP_ID>` | Discard one op, waiting or rejected, by the start of its id. |
| `--seed` | Also send nodes, edges and documents the server lacks that no op covers. Never changes a row the server has. |
| `--repair` | Also send what this copy changed and never logged, for nodes `status` lists as Different, field by field where the server has not changed the field since the last pull. |
| `--overwrite-server` | With `--repair`: also send fields the server did change, over the server's value. |
| `--overwrite` | Replace the server's copy of every row with the local one (the pre-1.0.3 behaviour). Last resort. |

`DECIDUOUS_OPS_TIMEOUT=<seconds>` changes the 120-second limit per request (see [Environment](#environment)).

### `remote pull` (server)

Refresh the local database from the server. It first refuses a workspace claimed by an unrelated repository, then sends the writes still waiting in `.deciduous/remote-log.jsonl`; if they cannot be sent it stops with `Nothing was pulled.` Then it takes the server's side of every difference. Run it before reading with `nodes`, `show` or `serve` if agents have been writing over MCP. No flags.

It also writes `.deciduous/graph.json`, `graph.json.lock` and `graph.json.follow.lock`, even in a project with a `[remote]`. The `.gitignore` block that `init` writes lets `graph.json` through on purpose, for projects with no server, so it shows up as untracked. Do not `git add` it in a server project; [Join a server, step 4](quickstart.md#4-install-the-agent-integration) says which line to delete.

### `remote watch` (server)

Stream this workspace's writes, one line per node event, reconnecting with backoff.

```text
$ deciduous remote watch
Watching: my-app
13:38:02  main      outcome     "watched outcome"
```

| Flag | Meaning |
| --- | --- |
| `--types <TYPES>` | Only these node types, comma-separated. |
| `--branch <BRANCH>` | Only this branch; repeat for several. |
| `--edges` | Also show edge events. |
| `--json` | Raw JSON frame per event. |
| `--url` | Print the socket URL and exit. The URL carries the token in its query string. |
| `--claude-code` | Print the URL plus a ready-to-paste Monitor tool call for Claude Code, and exit. Also carries the token. The printed call sets no `timeout_ms`, and a Claude Code monitor ends after its `timeout_ms` (default 5 minutes, at most 30), so the watch has to be started again. |

## Record decisions

### `add <TYPE> <TITLE>`

Types: `goal`, `option`, `decision`, `action`, `outcome`, `observation`, `revisit`. 1.1.0's `--help` omits `revisit`, which works; main's `--help` lists it.

| Flag | Meaning |
| --- | --- |
| `-d, --description <TEXT>` | Description. Observations warn without one. |
| `-c, --confidence <0-100>` | Confidence. |
| `-p, --prompt <TEXT>` | The user's request, verbatim. Any prompt under 200 characters gets a warning that it "looks like a summary"; the test is length only, and the node is created anyway. |
| `--prompt-stdin` | Read the prompt from stdin, for multi-line requests. |
| `-f, --files <a,b>` | Associated files, comma-separated. |
| `-b, --branch <BRANCH>` / `--no-branch` | Override or skip branch detection. |
| `--commit <REV>` | HEAD, a branch, a tag, a hash or prefix. Stored as the full hash; a rev git cannot resolve is refused. |
| `--date <DATE>` | Backdate: RFC 3339, `YYYY-MM-DD` or `YYYY-MM-DD HH:MM:SS`. |

```text
$ deciduous add goal "Bound the retry delay" -c 90 --prompt-stdin <<'EOF'
Retries should stop after a bounded delay; right now a 429 without Retry-After loops forever.
EOF
Warning: Prompt is only 93 chars. This looks like a summary, not a full prompt.
         Capture the verbatim user message for better context recovery.
Created node 3 (type: goal, title: Bound the retry delay) [confidence: 90%] [prompt: 93 chars] [branch: main]
```

That prompt is verbatim; the warning fires because it is short.

### `link <FROM> <TO>` / `unlink <FROM> <TO>`

`link -r, --rationale <TEXT>`, `-t, --edge-type <TYPE>` (default `leads_to`; also `requires`, `chosen`, `rejected`, `blocks`, `enables`, `took_from`). `unlink -t, --type <TYPE>` removes only the edge of that type, required when two nodes are joined by more than one.

### `status <ID> <STATUS>`

`pending`, `active`, `completed`, `rejected`, `superseded`, `abandoned`. 1.1.0's `--help` lists only the first four; all six work, and main's `--help` lists all six.

### `prompt <ID> [PROMPT]`

Set or replace a node's prompt; reads stdin when the text is omitted.

### `delete <ID>`

Delete a node and its edges. `--dry-run` shows what would go.

## Read the graph

| Command | Flags |
| --- | --- |
| `nodes` | `-b, --branch`, `-t, --node-type`, `--theme` |
| `edges` | none |
| `show <ID>` | `--json` |
| `graph` | none; the whole graph as JSON on stdout |
| `pulse` | `-b, --branch`, `-r, --recent <N>` (default 10), `--json`, `--summary`. Active state, gaps, health. |
| `serve` | `-p, --port` (default 3000). The web viewer, on the local database. |
| `commands` | `-l, --limit` (default 20). In 1.1.0 it always prints `No commands logged.`: nothing writes the log. Main records each write as it starts and marks it `(exit 0)` when it finishes; a command that fails stays `(unfinished)`, with no exit code. |

All of these read the local database. Over MCP, agents read the server directly; see [MCP tools](mcp.md).

## Design history

| Command | Purpose and flags |
| --- | --- |
| `archaeology pivot <FROM_ID> <OBSERVATION> <NEW_APPROACH>` | Creates observation -> revisit -> new decision and marks the old one superseded, in one step. `-c, --confidence`, `-r, --reason`, `--dry-run`. |
| `archaeology supersede <ID>` | Mark superseded. `--cascade` for every descendant, `--dry-run`. |
| `archaeology timeline` | Nodes in time order. `-l, --limit` (0 = all), `-t, --node-type`, `-b, --branch`, `--json`. |
| `narratives init` / `show` / `pivots` | `.deciduous/narratives.md`: seed it with a section per goal that is not superseded or abandoned (`-o`, `--force`), print it (`-p`), list revisit chains (`-b`, `--json`). |

See [Design history](history.md).

## Evidence

| Command | Purpose and flags |
| --- | --- |
| `doc attach <NODE_ID> <FILE>` | Attach a file. `-d, --description`, `--ai-describe` (uses the `claude` CLI). |
| `doc list [NODE_ID]` | `--include-detached`, `--json`. |
| `doc show <DOC_ID>` / `doc open <DOC_ID>` | Details (`--json`) / open in the default application. |
| `doc describe <DOC_ID> [TEXT]` | Set the description; stdin if omitted; `--ai`. |
| `doc detach <DOC_ID>` | Soft-delete. `doc gc [--dry-run]` removes files nothing references. |
| `transcript list` | This project's Claude Code sessions and whether each is imported. `--dir`, `--json`. |
| `transcript import <PATH or SESSION-ID>...` | Derive goals, actions and outcomes from a transcript, each with evidence. Re-importing adds nothing. `--dry-run`, `--no-hash`, `--json`. |

See [Documents and transcripts](evidence.md).

## Coordinate agents

`board post -s, --subject <S> [-m <BODY>]` (body from stdin if omitted), `--as <LABEL>` (default `$DECIDUOUS_AGENT_LABEL`), `--reply-to <ID>`, `--branch`, `--json`. `@label` in the subject or body addresses someone.

`board read`: `--unanswered <LABEL>` (what is waiting on you), `--to`, `--from`, `--since <ID>`, `-q, --query`, `--limit` (default 50, max 200), `--json`. `board show <ID> [--json]`.

With a `[remote]` the board lives on the server, per workspace; without one, in the main worktree's database. Messages are not graph nodes and are never exported. See [The message board](board.md).

## Export

| Command | Flags |
| --- | --- |
| `dot` | `-o`, `-r, --roots`, `-n, --nodes "1-11"`, `--png` (needs graphviz), `--auto` (branch-specific name in `docs/`), `-t, --title`, `--rankdir TB\|LR\|BT\|RL` |
| `writeup` | `-t, --title`, `-r, --roots`, `-n, --nodes`, `-o`, `--png <FILE>`, `--auto`, `--no-dot`, `--no-test-plan` |
| `backup` | `-o, --output` (default `deciduous_backup_<timestamp>.db`). Copies the local database only; back up the server's PostgreSQL separately ([Operating](operating.md)). |

## Themes and tags (local only)

`themes create <NAME> [-c '#hex'] [-d TEXT]`, `themes list`, `themes delete <NAME>`; `tag add|remove|confirm <NODE_ID> <THEME>`, `tag list <NODE_ID>`, `tag suggest [NODE_ID] [--apply]`. These stay in the local database: they are not sent to the server, and `remote status` does not compare them.

## Without a server (no server)

| Command | Purpose |
| --- | --- |
| `sync` | Reconcile `.deciduous/graph.json` with the local database, both ways, and register the git merge driver in this clone. `--check` reports without writing. |
| `migrate` | Add change_id columns to a pre-sync database. |

See [Without a shared server](local.md#no-server-at-all).

## Project setup

| Command | Purpose and flags |
| --- | --- |
| `init` | Set up the project: `.deciduous/`, assistant files, and the server step. `--claude` (default), `--opencode`, `--windsurf`, `--both`, `--no-auto-update`. Without a terminal and without a `[remote]`, exits 1 after writing its files; `DECIDUOUS_NO_SERVER=1` skips the server step. |
| `update` | Refresh the assistant integration files deciduous wrote, keeping yours (backups in `.deciduous/update-backups/<time>/`). Leaves `.deciduous/config.toml` alone. In a project on this machine's native server, upgrades that server too. `--all <DIR>` for DIR and each project one level below it (not recursive). |
| `check-update` | Exit 1 when `.deciduous/.version`, relative to the current directory, is missing or older than the binary. Run it from the project root: in a subdirectory it says `Update needed: No version file found`. A project only joined with `remote init` or `remote setup` has no `.version` until `init` or `update` writes the assistant files. |
| `auto-update on\|off` | The once-a-day crates.io version check. |
| `integration` | Show Claude Code hooks, commands and skills installed. |
| `hooks install\|status\|uninstall` | Claude Code hooks from the `[hooks]` lists in `.deciduous/config.toml`, which are empty by default. See the warning below. |
| `opencode install\|status\|uninstall` | OpenCode plugins, commands and `AGENTS.md`. |
| `completion <SHELL>` | `bash`, `zsh`, `fish`, `powershell`, `elvish`. |

Do not run `hooks install` or `hooks uninstall` unless you have listed hooks in `config.toml`. Both rewrite the hooks in `.claude/settings.json` from those lists. In a project set up by `init`, `hooks install` left `{"PostToolUse": [], "PreToolUse": []}`, removing the version-check and board-mentions hooks `init` installed and any hooks of your own; `uninstall` also deletes `.claude/hooks/`. `deciduous update` puts the board-mentions hooks back, but not the version-check entry (1.1.0 and main). 1.1.0's `hooks --help` still says "pre-edit blocks, post-commit reminders"; deciduous has shipped no such hooks since 1.0.3, and main's help says so.

## Other commands

`mcp` runs the stdio MCP server on the local database ([MCP tools](mcp.md)). `serve --api` runs a separate multi-graph JSON daemon (`--data-dir`, `--token`, `--bind`, default `127.0.0.1`); it is not the graph server. `audit --associate-commits` matches commits to nodes by title (`--min-score`, `--dry-run`, `--yes`). `roadmap init|refresh|sync|list|link|unlink|conflicts|status|check` keeps `ROADMAP.md` in step with GitHub issues; `sync` is a dry run unless `--execute`.

## Environment

| Variable | Effect |
| --- | --- |
| `DECIDUOUS_MCP_TOKEN` | Token for the server. Read before the stored token. |
| `XDG_CONFIG_HOME` | Moves `~/.config/deciduous/` (credentials, and this machine's server settings). |
| `DECIDUOUS_NO_SERVER` | Any value other than empty or `0` makes `init` and `update` skip the server step. |
| `DECIDUOUS_PORT` | Port for this machine's server the first time `remote setup --local` installs it. |
| `DECIDUOUS_DB_PATH` | Use this SQLite file instead of finding `.deciduous/deciduous.db` by walking up (Claude Desktop, unusual layouts). |
| `DECIDUOUS_API_DATA_DIR`, `DECIDUOUS_API_TOKEN` | Fallbacks for `serve --api`'s `--data-dir` and `--token`. |
| `DECIDUOUS_OPS_TIMEOUT` | Seconds per `POST /ops` request in `remote push`, `pull` and `init` (default 120). Anything but a positive integer makes those commands fail: `DECIDUOUS_OPS_TIMEOUT="abc" is not a number of seconds above zero`. The send after an ordinary write has a fixed 10-second budget this does not change. |
| `DECIDUOUS_AGENT_LABEL` | Default `--as` for `board post`. |
| `DECIDUOUS_QUIET_LOCAL_ONLY` | Silences the "written to ... only; this project has no shared server" note. |
| `DECIDUOUS_SERVER_BINARY`, `DECIDUOUS_SERVER_BUNDLE` | A local server executable or Docker bundle for `remote setup --local` to install instead of downloading one (unreleased builds). |

---

<!-- https://deciduous.dev/content/mcp.md -->

# MCP tools

There are two MCP servers with different tool sets, and an agent gets whichever one its client is configured for.

- **The graph server** answers at `<base>/mcp` over HTTP with 21 tools and writes PostgreSQL directly. This is what `remote setup` registers with Claude Code and what this page is mostly about.
- **`deciduous mcp`** is a stdio server with a different set of 34 tools. It writes the local database, and in a project with a `[remote]` those writes go on to the server through the CLI's op log, exactly like `deciduous add`. Nothing configures it for you, and it does not send the server's logging instructions.

Seven tools share a name across the two. Five of those take different arguments and ids; `post_message` and `read_messages` take the same arguments on both, and in a project with a `[remote]` they reach the same board, with the same message ids. The two lists below are from `tools/list` against deciduous 1.1.0 on 2026-11-08.

## Which one an agent has

| | Graph server (`<base>/mcp`) | `deciduous mcp` (stdio) |
| --- | --- | --- |
| Transport | Streamable HTTP, `Authorization: Bearer <token>` | stdin/stdout, a process per session |
| Configured by | `remote setup` (Claude Code, user scope, if none is registered), or by hand: [Connect your agents](clients.md) | you, in the client: `{"command": "deciduous", "args": ["mcp"]}`, started inside the project (see below) |
| Writes go to | PostgreSQL, at once, visible to every agent | the local database; in a project with a `[remote]`, also queued in `.deciduous/remote-log.jsonl` and sent to the server, as CLI writes are. Without a `[remote]`, they stay local. |
| Reads come from | the server | the local database, which is a cache: it shows what other agents wrote only after `deciduous remote pull` |
| Tools | 21 | 34 |
| Prompts | 1 (`always_capture`) | none (`prompts/list` answers `-32601 Unknown method`) |
| `initialize` reply | `serverInfo {name: deciduous-mcp, version}` plus `instructions` (the logging rules agents follow) | `serverInfo {name: deciduous, version}`, no `instructions` |

The stdio server finds its database the way the CLI does: `DECIDUOUS_DB_PATH` if set, otherwise the first `.deciduous/` in the directory it was started in or above. If there is none, it creates `.deciduous/deciduous.db` in that directory and writes there, local-only. A client that starts it from your home directory, `/` or its own application directory writes a separate graph the project never sees. Start it inside the project, or give it the path:

```json
{"command": "deciduous", "args": ["mcp"],
 "env": {"DECIDUOUS_DB_PATH": "/abs/path/to/my-app/.deciduous/deciduous.db"}}
```

Use the graph server for agents. The stdio server is for a project with no server at all ([Without a shared server](local.md)) or for the local-only tools it has that the graph server lacks (themes, DOT export, writeups, sessions).

A stdio write in a project with a `[remote]` was checked: `add_node` over `deciduous mcp` returned `Created observation node #3`, and `deciduous remote status` then said In sync with the server holding the node.

## Talking to the graph server by hand

An MCP client does this for you. With `curl`, the sequence is: `initialize` without a session id, read `mcp-session-id` from the response headers, send `notifications/initialized` with that id, then make calls with it. `Accept` must list both `application/json` and `text/event-stream`.

```bash
BASE=https://deciduous.example.com
H=(-H "Authorization: Bearer $DECIDUOUS_MCP_TOKEN" -H 'Content-Type: application/json'
   -H 'Accept: application/json, text/event-stream')

curl -s -D headers.txt -X POST "$BASE/mcp" "${H[@]}" -d '{"jsonrpc":"2.0","id":1,"method":"initialize",
  "params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"probe","version":"0"}}}'
SID=$(grep -i '^mcp-session-id' headers.txt | awk '{print $2}' | tr -d '\r')

curl -s -X POST "$BASE/mcp" "${H[@]}" -H "mcp-session-id: $SID" \
  -d '{"jsonrpc":"2.0","method":"notifications/initialized"}'
curl -s -X POST "$BASE/mcp" "${H[@]}" -H "mcp-session-id: $SID" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'
```

Skip `notifications/initialized` and the session is dropped: the next call gets HTTP 404 `Session not found` with `This session expired or the server restarted. Send a new initialize request without a session id to start another.` The same reply follows a server restart. `GET /mcp` answers 405; there is no server-to-client stream.

Tool results come back as JSON text inside `result.content[0].text`. A tool error is a JSON-RPC `error` whose `message` says what was wrong, including any argument the tool does not have:

```text
query_nodes has no argument "bogus". Its arguments are: branch, file, limit, search, status, type, workspace
```

## Workspace and branch on every call

Every tool except `list_workspaces` takes `workspace`. Pass the `workspace` under `[remote]` in `.deciduous/config.toml`, the name the CLI uses. For every tool that does not name a node by id, the server picks the workspace in this order:

1. The `X-Deciduous-Workspace` header, if the client sends one (a repository's `.mcp.json` can). It wins over the argument: an `add_node` sent with `"workspace": "elsewhere-xyz"` on a connection pinned to `my-app` landed in `my-app`.
2. The call's `workspace` argument.
3. `scratch`.

Read tools accept `"workspace": "*"` for all workspaces at once; on a pinned connection `*` reads the pinned workspace only, without an error. Writes refuse it. A read naming a workspace that does not exist is an error; the first write creates it.

Tools that take a node id (`show_node`, `update_node`, `delete_node`, `delete_edge`, `get_ancestors`, `get_descendants`) always act in that node's own workspace, and never fall back to `scratch`. Their `workspace` argument is only a guard against acting on the wrong one:

```text
node e2eee285-... is in workspace "wf-ref-fix-s1", not "wf-ref-fix-s2". Pass the node's own workspace, or none
```

On a pinned connection, a node outside the pin is refused: `node e2eee285-... belongs to another workspace than the one this client is pinned to`.

Pass `branch` on every write. The server cannot see the agent's checkout, and `check_activity` shows writers by branch. Nothing is locked: since 1.0.8 there are no branch leases, and two sessions writing one branch both succeed.

## The 21 graph-server tools

Required arguments in bold. Node ids are full server UUIDs (the `id` in every result); prefixes are refused.

### Write

| Tool | Arguments | Notes |
| --- | --- | --- |
| `add_node` | **`node_type`**, **`title`**, `description`, `status`, `confidence`, `prompt`, `files`, `commit`, `branch`, `parent_id`, `edge_type`, `rationale`, `change_id` | `parent_id` creates and links in one transaction (`edge_type`, `rationale` apply to that edge). A non-goal node without a parent comes back with `suggested_parents`, never linked for you. A repeated `change_id` returns the existing node with `created: false`. |
| `add_edge` | **`from_node_id`**, **`to_node_id`**, `edge_type`, `rationale`, `branch` | For `took_from`, `from` is the node the idea came from. Never in the same batch as the `add_node` whose id it needs. |
| `update_node` | **`node_id`**, `title`, `description`, `status`, `metadata`, `branch` | `metadata` is merged: keys sent are set, a key sent as `null` is removed, others are kept. |
| `delete_node` | **`node_id`**, `branch` | Soft delete. |
| `delete_edge` | **`from_node_id`**, **`to_node_id`**, `edge_type`, `branch` | `edge_type` defaults to `leads_to`. |
| `log_observation` | **`title`**, `description`, `related_to`, `took_from`, `why`, `tags`, `branch` | `related_to` and `took_from` take a UUID or a full change_id. `why` becomes the `took_from` edge's rationale. |
| `log_decision` | **`title`**, **`chosen_option`**, `rejected_options`, `rationale`, `parent_node_id`, `confidence`, `branch` | One transaction: decision, options, `chosen`/`rejected` edges. Options are objects or plain titles. |
| `capture_conversation_turn` | **`summary`**, `goal`, `observations`, `options_considered`, `decision`, `action`, `outcome`, `parent_node_id`, `confidence`, `branch` | One step's nodes and edges, all or nothing. `parent_node_id` hangs it under the goal in progress. |
| `close_thread` | **`title`**, `description`, `parent_node_id`, `goal_node_id`, `success`, `lessons_learned`, `next_steps`, `branch` | Writes the outcome; `goal_node_id` marks the goal completed; lessons become observations, next steps become goals. |

### Read

| Tool | Arguments | Notes |
| --- | --- | --- |
| `list_workspaces` | none | Every workspace with node and edge counts. |
| `check_activity` | `branches` (default 20) | Who wrote to this workspace in the last five minutes (branch, client, whether it is you), and the newest node on each branch. Call before a burst of writes. |
| `query_nodes` | `type`, `status`, `branch`, `search`, `file`, `limit` (default 100) | `file` matches `metadata.files`. `type` also accepts legacy `feedback`, `status` legacy `done`. |
| `show_node` | **`node_id`** | The node, its edges, documents, themes, and up to 10 `related` nodes sharing a file or commit. Takes a UUID, not a change_id. |
| `get_graph` | `branch`, `include_details`, `max_nodes` (default 2000) | Refuses a larger graph rather than truncating. |
| `get_ancestors` / `get_descendants` | **`node_id`**, `max_depth` (default 50), `max_nodes` (default 1000) | Walk edges backward / forward. |
| `find_orphans` | `suggest_parents` | Non-goal nodes with no incoming edge; with `suggest_parents`, ranked guesses for the first 25. |
| `ask_graph` | **`question`**, `scope` (`all`, `active`, `decisions`, `goals`, `observations`, `recent`), `include_context` (default true) | Text search (trigram and full text), then follows the edges the question implies. Says how each result was reached, and stops early when a distinctive word in the question matches nothing. Not a language model. |
| `consolidation_report` | `similarity` (0.6), `stale_days` (14), `max_nodes`, `max_pairs`, `max_items` | Proposes merges, missing revisits, stale actions and parents. Changes nothing. |

### Message board

| Tool | Arguments |
| --- | --- |
| `post_message` | **`author`**, **`subject`**, **`body`**, `reply_to`, `branch` |
| `read_messages` | `unanswered_for`, `to`, `author`, `branch`, `query`, `since_id`, `id`, `limit` (default 50) |

Messages are per workspace and are not graph nodes. See [The message board](board.md).

### Prompt

The graph server also offers one MCP prompt, `always_capture`, with an optional `verbosity` argument: `full` logs every exchange, `decisions_only` only decision points and outcomes, `minimal` only major milestones. Claude Code lists MCP prompts as commands, named `/servername:promptname (MCP)` ([Claude Code: Use MCP prompts as commands](https://code.claude.com/docs/en/mcp)), so with the server registered as `deciduous` it is `/deciduous:always_capture`. The stdio server has no prompts.

## The 34 stdio tools

`deciduous mcp` exposes: `add_node`, `attach_document`, `create_theme`, `delete_node`, `end_session`, `export_dot`, `find_orphans`, `generate_writeup`, `get_branch_summary`, `get_graph`, `get_node_context`, `get_pulse`, `get_session`, `get_timeline`, `link_nodes`, `list_documents`, `list_edges`, `list_nodes`, `list_sessions`, `list_themes`, `post_message`, `read_messages`, `resume_session`, `search_nodes`, `show_node`, `start_session`, `sync`, `sync_status`, `tag_node`, `trace_chain`, `unlink_nodes`, `untag_node`, `update_prompt`, `update_status`.

Where a name matches a graph-server tool, other than the two board tools, the arguments and ids still differ: stdio tools take a local node number (`Created observation node #3`) or a change_id prefix, never a server UUID (`No node has a change_id starting with 'e2eee285-...'`, even though the CLI accepts one); the graph server takes UUIDs. Where the job matches, the name differs: `link_nodes` vs `add_edge`, `list_nodes`/`search_nodes` vs `query_nodes`, `update_status` vs `update_node`. An agent moved from one server to the other with instructions written for the first will hit `has no argument` and unknown-tool errors; [For agents](for-agents.md) is written for the graph server.

---

<!-- https://deciduous.dev/content/architecture.md -->

# Architecture and trust

The graph lives in PostgreSQL behind one server process. Agents reach that server over HTTPS MCP; the CLI reaches the same server, over the same HTTPS and token, through ordinary JSON endpoints (`/ops`, `/export`, `/events`) rather than MCP, sending each write from a local log of operations. Each developer's `.deciduous/deciduous.db` is a cache of the server's copy, not a second source of truth. One bearer token opens the whole server: every workspace, read and write.

## What runs where

```text
 developer machine                                   the server's host
 ┌───────────────────────────────┐                   ┌──────────────────────────────┐
 │ agent (Claude Code, ...)  ────┼── POST /mcp ─────►│ deciduous-mcp (Elixir)       │
 │                               │   Bearer <token>  │   /mcp  /ops  /export        │
 │ deciduous CLI                 │                   │   /events /blob /documents   │
 │   .deciduous/deciduous.db     │── POST /ops ─────►│   /health /ready             │
 │   (cache)                     │◄─ GET /export ────│                              │
 │   .deciduous/remote-log.jsonl │                   │          │                   │
 │   (writes not yet sent)       │◄─ WS /events ─────│          ▼                   │
 └───────────────────────────────┘                   │   PostgreSQL: every          │
                                                     │   workspace's nodes, edges,  │
                                                     │   documents, messages        │
                                                     └──────────────────────────────┘
```

| Piece | Where | What it holds |
| --- | --- | --- |
| `deciduous-mcp` | A VM behind a TLS proxy ([Run a server](run-a-server.md)), or this machine ([Without a shared server](local.md)) | Nothing durable. Speaks MCP at `/mcp`, applies CLI ops at `/ops`, serves exports, documents and the event socket. |
| PostgreSQL | Next to the server, or managed | Every workspace: nodes, edges, document bytes, board messages, workspace claims, write activity. Back this up; it is the graph. |
| `.deciduous/deciduous.db` | Each clone | A cache of one workspace, plus themes, tags and the local command log, which the server does not have. |
| `.deciduous/remote-log.jsonl` | Each clone, next to the cache | CLI writes the server has not acknowledged. With it: `remote-delivered.jsonl` and `remote-log.lock`. |
| `.deciduous/config.toml` | Each clone, committed | `[remote] url` and `workspace`. Never a token. |
| `~/.config/deciduous/credentials` | Each machine | The one stored token. |

The cache, the log and `.deciduous/documents/` (local copies of attached files, secrets included) are ignored by git only if `deciduous init` wrote the `.gitignore` block (`.deciduous/*`, with `config.toml` and `graph.json` let back in). A clone joined with `deciduous remote init <url>` alone gets no ignore rules, and `git status` then lists `deciduous.db`, `remote-log.jsonl`, `remote-delivered.jsonl` and `remote-log.lock` as untracked, ready for a careless `git add`. Add the block by hand in that case.

The server's HTTP routes: `/health` (unauthenticated, process liveness), `/ready` (database and migrations), `/mcp`, `/ops`, `/export`, `/import`, `/claim`, `/locate`, `PUT /blob/:hash`, `/documents/:id`, `/messages`, `/events`. Everything except `/health` and `/ready` requires the token.

## Two write paths, one store

An agent's MCP write is a transaction in PostgreSQL. When the tool returns, every other agent can read it.

A CLI write (`deciduous add`, `link`, `status`, and `deciduous mcp` over stdio in a project with a `[remote]`) goes through three steps:

1. The write and an op describing it commit together in the local database (the op sits in a `remote_outbox` table), so a crash cannot keep one without the other.
2. The op is appended to `.deciduous/remote-log.jsonl`. An op names only what changed: `{"kind":"update_node","change_id":"…","set":{"status":"completed"}}`, not the whole node.
3. Before the command exits, the waiting ops are sent to `POST /ops`, with a 10-second budget. The server applies each op at most once, by `op_id`, field by field. Acknowledged ops are removed from the log.

If step 3 fails, the command still exits 0, prints why, and the op waits. The next write that gets through sends everything queued before it; `deciduous remote push` sends it on demand. `remote status` lists what waits and what the server rejected. The log is why an edit made while the server was down still arrives, and why a status change does not resend (and overwrite) a title an agent changed meanwhile; through 1.0.7 the CLI pushed whole nodes by comparing snapshots and did both. [Troubleshooting](troubleshooting.md#the-local-write-succeeded-but-the-server-did-not-get-it) shows the output.

There are no locks. Until 1.0.8 every MCP write took a ten-second lease on its workspace and branch; it refused one-shot clients their own next call and could not cover CLI ops replayed later, so it was removed. Each write is atomic on its own, `capture_conversation_turn`, `log_decision` and `close_thread` included, and the server records who wrote where so `check_activity` can show it.

## The local database is a cache

CLI reads (`nodes`, `show`, `pulse`, `serve`, `writeup`) read the local database. It does not refresh itself. After agents write over MCP, `remote status` shows the gap and `remote pull` closes it:

```text
                 local    server
  nodes              1         2

Only on the server (1)
  observation 96096527 "MCP probe obs"

Differs: `deciduous remote pull` takes the server's side.
```

Themes and tags exist only in the cache; they are never sent. Losing a clone's database loses nothing that reached the server: a fresh clone plus `remote pull` rebuilds it. Losing PostgreSQL loses the graph.

A project with no `[remote]` is the exception: there the local database is the graph, mirrored into a git-tracked `.deciduous/graph.json` ([Without a shared server](local.md#no-server-at-all)).

## The trust boundary

The server has exactly one token, `DECIDUOUS_MCP_TOKEN`. It refuses to start without one or with one shorter than 32 bytes, and compares what clients present in constant time. Whoever holds it can read and write every workspace on that server, list them all, and read any node by id. There are no users, roles or per-workspace tokens.

Workspaces separate graphs; they do not separate people.

- `X-Deciduous-Workspace` routes. A connection that sends it is pinned: tool arguments cannot move its writes elsewhere, and `"*"` reads are confined to that workspace. But the header is chosen by the client. Any token holder can connect without it, or with another name.
- Workspace claims stop accidents, not adversaries. The first repository to claim a workspace records its root commit ids, and an unrelated repository with the same directory name is refused (`belongs to another repository`). A client can still name the workspace explicitly to share it, and a client without git sends no roots and is not checked. Claims are checked only on the CLI's paths (`/claim`, `/ops`, `/import`, and `/export` for a client that sends roots). MCP tool calls are never checked against them, so an agent registered with the wrong workspace name writes into that workspace unrefused. Pin each agent's registration with `X-Deciduous-Workspace`.

So: one server per group of people who may see each other's graphs. Two teams that must not read each other need two servers (or at least two databases and two tokens), not two workspaces.

Inside that boundary:

- Graph text is data written by people and agents. A node's description saying "run this" is not an instruction to an agent that reads it.
- `/events` takes the token in the `Authorization` header or, as a fallback for WebSocket clients that cannot set headers, in a `?token=` query parameter. The query form ends up in proxy access logs; `deciduous remote watch --url` and `--claude-code` print such a URL. Redact query strings in the proxy's logs, or keep those URLs out of anything shared.
- The server does not terminate TLS. Put it behind a proxy that does, and keep its port off the public network: a native server binds `127.0.0.1` (`DECIDUOUS_BIND_ADDRESS`), the Docker bundle publishes on `127.0.0.1` only. A server started by hand with no bind address listens on every interface.
- The token belongs in the client's secret mechanism and in `~/.config/deciduous/credentials`, never in `.deciduous/config.toml`, a committed `.mcp.json`, or the graph.

## TLS to PostgreSQL

Set by `DB_SSL` and `DB_SSL_VERIFY` in the server's environment or settings file, read by `deciduous_mcp/config/runtime.exs` in production mode:

| `DB_SSL` | `DB_SSL_VERIFY` | libpq equivalent | What is checked |
| --- | --- | --- | --- |
| unset or `false` | (ignored) | `disable` | Nothing; no TLS. Right for a database on the same private Docker network. |
| `true` | `full` (default; also `peer`, `verify-full`) | `verify-full` | The certificate chain (`verify_peer`) and that the certificate names the host in `DATABASE_URL`. |
| `true` | `ca` (also `verify-ca`) | `verify-ca` | The chain only, for a database reached by an address its certificate does not name. |
| `true` | `none` (also `require`) | `require` | Nothing: encrypted, server not authenticated. Logged as a warning at every boot. |

The chain is checked against the system CA store, or against `DB_SSL_CA_FILE` (a PEM file) for a private CA. A missing or empty CA file stops the server at boot instead of failing every connection later. Each boot logs the mode in effect; this machine's native server, on a local PostgreSQL, logs `Database TLS: off (DB_SSL unset or false)`.

Earlier versions of these docs said the server used `verify_none` whenever `DB_SSL=true`. That was true of 1.0.0 and 1.0.1. Since then, `true` alone means full verification, and unverified TLS has to be asked for by name. A 1.0.1 deployment upgrading with a private CA needs `DB_SSL_CA_FILE`; one whose certificate does not name the address it connects to needs `DB_SSL_VERIFY=ca`.

## Source map

| Path | What is there |
| --- | --- |
| `deciduous_mcp/lib/deciduous_mcp/web/router.ex` | Every HTTP route |
| `deciduous_mcp/lib/deciduous_mcp/web/auth.ex`, `workspace_plug.ex` | The token check; the workspace pin |
| `deciduous_mcp/lib/deciduous_mcp/mcp/scope.ex` | How a call's workspace is decided |
| `deciduous_mcp/lib/deciduous_mcp/mcp/tools/` | The 21 tools |
| `deciduous_mcp/lib/deciduous_mcp/activity.ex` | Write activity, and why the branch lock went |
| `deciduous_mcp/lib/deciduous_mcp/graph/workspaces.ex` | Workspace claims by root commit |
| `deciduous_mcp/config/runtime.exs` | Every setting the server reads, including database TLS |
| `src/oplog.rs` | The op log: format, crash safety, compaction |
| `src/remote.rs` | `remote *`, token lookup, status and pull |
| `src/server.rs`, `src/local_server.rs` | `remote setup` and this machine's server |
| `src/records.rs` | `graph.json` and the merge driver, for projects with no server |
| `src/mcp/` | The stdio MCP server |

---

<!-- https://deciduous.dev/content/developer.md -->

# Develop deciduous

The repository holds three things that are built and tested separately: the Rust CLI at the root (`cargo`), the graph server in `deciduous_mcp/` (Elixir, `mix`), and two web builds, the graph viewer in `web/` and this documentation site in `scripts/docs/`. A change to a tool's behaviour usually needs both the Rust and the Elixir side: the CLI's `deciduous mcp` and the server's `/mcp` are separate implementations with different tool sets ([MCP tools](mcp.md)).

## The CLI

The toolchain is pinned in `rust-toolchain.toml` to 1.92.0, with clippy and rustfmt; rustup picks it up from the file. Stable is pinned on purpose: a newer clippy reported 29 errors on an unchanged tree once.

```text
$ cargo build
   Compiling deciduous v1.1.0 (/Users/you/code/deciduous)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 8.36s
```

(an incremental build; a clean one takes minutes). Before committing, run this. It covers what `.github/workflows/type-check.yml` checks (formatting, `cargo test --lib`, `--test cli_integration`, clippy with warnings denied, the type validation) and more. The repository's `CLAUDE.md` lists only `cargo test`, `cargo build --release` and a plain `cargo clippy`, and a branch that passes those can still fail CI on formatting or on a clippy warning:

```bash
cargo fmt --check
cargo test
cargo clippy --all-targets -- -D warnings
cargo build --release
./scripts/validate-types.sh   # needs jq
```

Use `./target/debug/deciduous` or `./target/release/deciduous` when checking a change. The `deciduous` on your PATH is whatever you installed, and it will happily answer instead.

### `cargo test` on a Mac with Homebrew

`tests/git_sync_integration.rs` drives real git with the freshly built binary as the merge driver. It builds the PATH for each simulated developer from the directory holding `git`, and refuses to run if that directory also holds an installed `deciduous`, which would stand in for the binary under test. With Homebrew's git and Homebrew's deciduous both in `/opt/homebrew/bin`, every test in that file fails at once:

```text
thread 'a_merge_whose_ancestor_will_not_parse_is_refused_not_decided_by_timestamp' panicked at tests/git_sync_integration.rs:43:5:
git shares a directory with an installed deciduous (/opt/homebrew/bin)
```

That is the test protecting itself, not a bug. Put the system git first:

```bash
PATH=/usr/bin:$PATH cargo test
```

```text
$ PATH=/usr/bin:$PATH cargo test --test git_sync_integration a_merge_whose_ancestor
test a_merge_whose_ancestor_will_not_parse_is_refused_not_decided_by_timestamp ... ok
test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 23 filtered out; finished in 3.09s
```

The full suite run that way passed 687 tests on 2026-11-08. It is slow; filter by test binary (`--test <name>`) or name while iterating.

Tests that run `deciduous init` in a temporary directory need `DECIDUOUS_NO_SERVER=1`, or `init` stops at the server step ([Troubleshooting](troubleshooting.md#init-stops-with-no-terminal-to-ask)).

### Templates

`deciduous init` and `update` write files from templates in `src/init/`. `src/init/known_templates.rs` is generated: the sha256 of every template ever shipped, which is how `update` tells a file deciduous wrote from one a user edited. It is built from every template text in the repository's git history, so regenerate it after a template change is committed: `python3 scripts/gen_known_templates.py --write`. A template text missing from the list is one `update` will treat as the user's and keep.

## The graph server

`deciduous_mcp/` is an Elixir application (`mix.exs` declares Elixir `~> 1.16`; CI uses Elixir 1.18.4 on OTP 28.3.3). It refuses to boot without a `DECIDUOUS_MCP_TOKEN` of at least 32 bytes, tests included. `mix test` creates and migrates its database first (the `test` alias), using `PGHOST`, `PGUSER`, `PGPASSWORD` (default `postgres`/`postgres` on localhost) and database `deciduous_mcp_test`. CI's job, in `.github/workflows/integration.yml`:

```bash
cd deciduous_mcp
export MIX_ENV=test PGHOST=localhost PGUSER=postgres PGPASSWORD=postgres
export DECIDUOUS_MCP_TOKEN=mix-test-token-not-a-secret-0000000000000000
mix local.hex --force
mix local.rebar --force
mix deps.get
mix test
```

against a `postgres:17-alpine` service. Without the two `local.*` lines, `mix deps.get` on a fresh Elixir install stops to ask before installing Hex. Development (`config/dev.exs`) uses `deciduous_mcp_dev` with the same credentials. Neither was run for this page.

Things that are easy to get wrong here:

- A new tool lives in `lib/deciduous_mcp/mcp/tools/` and has to be registered with the server to appear in `tools/list`. Check the live list after a rebuild; the CLI's tools are a different list.
- Every tool's `workspace` argument is merged in by `DeciduousMcp.MCP.Scope`; resolve reads and writes through it so the `X-Deciduous-Workspace` pin is honoured.
- Unknown arguments are refused by name. A new argument has to be in the schema or clients get `has no argument`.
- A migration needs `STRUCTURE.sql` regenerated with it (from `deciduous_mcp/`, against a fully migrated, disposable PostgreSQL 17: `DATABASE_URL=ecto://postgres:postgres@localhost/deciduous_schema_check ./scripts/dump_structure.sh`, or `PGHOST` plus `PGDATABASE`; it exits without one of them). CI's `structure` job fails when they disagree.
- Server dependencies are audited at release: `mix hex.audit` must be clean or the self-contained server build fails.

Release executables are built with Burrito, which needs Zig 0.16.0 on PATH. `cd deciduous_mcp && MIX_ENV=prod BURRITO_TARGET=darwin_arm64 mix release deciduous_mcp` writes `burrito_out/deciduous_mcp_darwin_arm64`; without `BURRITO_TARGET`, `mix release` makes an ordinary release and no executable. `docker build -f deciduous_mcp/Dockerfile.burrito deciduous_mcp` builds only the Linux executable for the build machine's architecture. Neither was run for this page. To try an unreleased server through the CLI's own installer, point `DECIDUOUS_SERVER_BINARY` at that file (or `DECIDUOUS_SERVER_BUNDLE` at a Docker bundle) before `remote setup --local`. That installs a service on your machine; do it on a machine where that is what you want. `deciduous_mcp/DEPLOY.md` documents every server setting.

## The web viewer

`web/` is React and TypeScript in one `App.tsx`, built by Vite into a single HTML file that the CLI embeds. After changing anything under `web/src/`:

```bash
cd web && npm run build && cd ..
cp web/dist/index.html src/viewer.html
cp web/dist/index.html docs/demo/index.html
cargo test
cargo build --release
```

`deciduous serve` then serves the new viewer from the rebuilt binary. `npm run typecheck` and `npm test` (Vitest) run in `web/`. `scripts/validate-types.sh` checks that the TypeScript types in `web/src/types/` still match the Rust ones. These steps are from the repository's `CLAUDE.md` and `web/package.json`; they were not run for this page.

## This documentation

The site is generated from `docs/content/*.md` by `scripts/docs/`. Navigation and labels are in `scripts/docs/pages.json`; each page needs exactly one `# H1`, and its first paragraph becomes the page description. Links between pages are relative (`[Architecture](architecture.md)`).

```bash
npm ci --prefix scripts/docs
npm run build --prefix scripts/docs   # writes the HTML
npm run check --prefix scripts/docs   # verifies generated files match, then runs test.mjs
```

Generated HTML and the search index are committed with the Markdown; CI fails if they disagree. To look at it: `python3 -m http.server 8766 --directory docs --bind 127.0.0.1`.

## Releasing

The steps (both version numbers, both changelogs, `mix hex.audit`, tagging by hand from the merge commit, and watching `release.yml` until crates.io and the Homebrew tap show the version) are in the repository's `CLAUDE.md` under "Release Process". A release that looks finished may have published nothing; check `gh release view vX.Y.Z`, crates.io and the tap.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.