8000 No guide for adding an agent after install (#38) by simon-inkie · Pull Request #71 · simon-inkie/inkie-deck · GitHub
[go: up one dir, main page]

Skip to content
8000
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8000
65 changes: 65 additions & 0 deletions .specs/38-add-an-agent-guide/SPEC.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,65 @@
# #38: No guide for adding an agent after install

- Issue: [#38](https://github.com/simon-inkie/inkie-deck/issues/38)
- Branch: 38-add-an-agent-guide
- Started: 2026-10-16

## TL;DR

Adds `docs/adding-an-agent.md`, a short guide for someone who finished install
and wants another agent: create, naming rules, appearing in Deck, starting,
first message, removal, and the likeliest failures. Linked from INSTALL.md
"Where to go next" and the README. Written from a real run in a sandbox.

## Scope

In scope:
- The guide and two links to it.

Out of scope (and where it goes instead):
- A creation UI, a remove command, any script change (see Follow-ups).

## Acceptance

- A user can add a second agent following the guide alone.
- Covers create, verify, boot, first-boot prompts, day one, model choice.

## Test plan

Ran every step on a clean sandbox with a real Deck and a real runtime: create
(VERIFIED), bad name, duplicate name, agent visible in Deck, allowlist hiding
it (write returns 500), boot with trust prompt, a trust prompt answered No
(agent exited, day-one skipped), fix with `.first-boot-done` removal, message
sent from Deck and the reply arriving, removal and Deck dropping the agent.

## Decisions log

- Lives in `docs/` (new), linked from README and INSTALL.md.
- Command blocks use `text`, so the install rig does not execute them.
- Removal is documented as manual, since no script exists.

## Check results

Recorded in the PR.

## Follow-ups

- Killing the Deck launcher can leave the web-server child holding port 4242.
- A `remove-agent.sh` would make removal safer.

## Review feedb 8000 ack

Opus review of PR 71: approved with nits, nothing blocking. All fixed:

1. SPEC lacked a Log section: added.
2. Issue line is now a link.
3. Scope split into In scope and Out of scope.
4. Follow-ups have no issue links yet: left until filed.
5. README link sentence wrapped to 80 columns.
6. Dropped the redundant allowlist 500 sentence from the guide.
7. Guide now says 4242 is the default port.

## Log

- 2026-10-16: walk-through, guide, checks, PR 71 opened.
- 2026-10-16: Opus nits fixed.
2 changes: 2 additions & 0 deletions INSTALL.md
Original file line number Diff line number Diff line change
Expand Up @@ -1268,6 +1268,8 @@ only a display name: it is a filename in your inbox root. Checked: `mcUser` in

## Where to go next

- `docs/adding-an-agent.md`: adding a second agent once you are running:
create, verify, start, first message, remove, and what goes wrong.
- `README.md`: the layout, the checks the project runs on itself, and the
rules the machines enforce.
- `packages/base/README.md`: the persona-file pattern, the `inbox` CLI, and
8000 Expand Down
6 changes: 4 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,8 +7,10 @@ ties them together.
**To run it, see [INSTALL.md](INSTALL.md)**: three tiers, from a five-minute
sandbox on fixture data through a real production install to live agents in
tmux. Its shell blocks are extracted from the document and executed on every
rig run, so what it tells you to type is what was measured. The rest of this
file is about the repository itself.
rig run, so what it tells you to type is what was measured. To add another
agent once you are running, see
[docs/adding-an-agent.md](docs/adding-an-agent.md). The rest of this file is
about the repository itself.

## How this repository got its code

Expand Down
154 changes: 154 additions & 0 deletions docs/adding-an-agent.md
< 8000 td id="diff-a5f28bf11b29e85e4a6d0009452a676aa3012b5d280420bfd2d26473f28fef36R41" data-line-number="41" class="blob-num blob-num-addition js-linkable-line-number js-blob-rnum">
Original file line number Diff line number Diff line change
@@ -0,0 +1,154 @@
# Adding an agent

This is for when [INSTALL.md](../INSTALL.md) is finished, you have an agent
running, and you want a second one. It takes about ten minutes. Every step
below was run on a clean machine and the output shown is what came back.

The examples use `quill`, an agent that drafts a weekly summary. Use your own
name wherever you see it.

## What you are making

An agent lives in two places, and they have to agree:

- **Persona files** in `$AGENTS_HOME/quill/`: who the agent is. Its launcher
reads these.
- **An inbox** in `$INBOX_ROOT/quill/inbox/`: where messages to and from it
are kept. Deck reads these.

One command makes both. If you did the install with the usual settings,
`AGENTS_HOME` is `/home/you/agents` and `INBOX_ROOT` is `/home/you/deck/inbox`.
Use the same two values you used for your first agent. If you open a new
terminal, set them again.

## 1. Create it

```text
export AGENTS_HOME=$HOME/agents
export INBOX_ROOT=$HOME/deck/inbox
packages/base/bin/create-agent.sh quill --role "drafts the weekly summary" --model claude-sonnet-5-5
```

Choose the model on purpose. Without `--model` the agent uses your model
tool's default, which may cost more than you expect, and always-on agents add
up. You can change it later by editing `$AGENTS_HOME/quill/.model`.

The script prints where everything went, then proves the persona reached the
model by asking it for a phrase that exists only in its own identity file:

```text
create-agent: CREATED quill
persona files /home/you/agents/quill
inbox /home/you/deck/inbox/quill/inbox
...
create-agent: VERIFIED quill
```

`VERIFIED` is the only result that means it worked end to end. Exit codes:
`0` verified, `1` could not create it, `3` the model did not return the
phrase, `4` created but nothing to check with (no model tool installed).

### Naming rules

A name is lowercase letters, digits and hyphens, starting with a letter or
digit. It becomes a folder name, a tmux window name and a message address, so
it has to survive all three. `Quill`, `quill_2` and `my agent` are refused, and
the message suggests a fix (`Try "bad-name"`). A name that already exists is
also refused, and nothing is changed.

## 2. See it in Deck

Reload Deck. The agent is there, and nothing needs restarting: Deck's agent
list is the set of folders under `INBOX_ROOT`.

If it is missing, check `MC_INBOX_AGENT_ALLOWLIST` in `packages/deck/.env`
(or your environment). When that is set, it is a comma-separated list of the
only agents Deck will show. Add `quill` to it and restart Deck. Leave it
unset to show every agent.

## 3. Start it

```text
packages/base/bin/boot-agents.sh
```

This starts the agents that are not running and leaves the others alone, so
it is safe to run again. Each agent gets a window in a tmux session called
`agents`. Check with:

```text
tmux list-windows -t agents -F '#{window_name}'
```

The first time an agent starts, the launcher gives it a first message: do your
day-one steps, then say hello. It fills in `IDENTITY.md` and `SOUL.md` and may
ask you questions. Attach to answer them:

```text
tmux attach -t agents:quill
```

Detach again with `Ctrl-b` then `d`.

The model tool may ask setup questions the first time, such as whether you
trust the folder. **Read them and choose; do not press Enter blindly.** The
default for the trust question is No, which closes the agent.

## 4. Send it a first message

In Deck, open the agent's thread and write to it. Your message is saved as
`$INBOX_ROOT/quill/inbox/<MC_USER>.md`, where `MC_USER` is the name set in
`packages/deck/.env`. The agent answers in the same thread. We sent "please reply
with one sentence saying what you will do each Monday" and a reply arrived
within half a minute.

The agent may stop to ask permission to run its `inbox reply` command. That is
normal the first time. Attach, read the question, and choose "Yes, and don't
ask again" if you are happy for it to reply without asking.

## 5. Day one and what to expect

On its first turn the agent writes its identity and may ask you who you are
and what you want from it. Answer in plain words. You can edit `IDENTITY.md`,
`SOUL.md` and `USER.md` in `$AGENTS_HOME/quill/` at any time; they are
ordinary text files, and the agent reads them each time it starts.

## Removing an agent

There is no remove command. Stop it, then delete both places:

```text
tmux kill-window -t agents:quill
rm -rf "$AGENTS_HOME/quill" "$INBOX_ROOT/quill"
```

Deleting the inbox deletes the conversation history, so copy it somewhere
first if you want it. If you use `MC_INBOX_AGENT_ALLOWLIST`, take `quill` out
of it. Deck stops listing the agent straight away. Check that
`curl -sS http://localhost:4242/` (4242 is the default port) no longer
mentions it.

## If something goes wrong

**The name is refused.** Read the message: it says why and offers a fix. Use
lowercase letters, digits and hyphens only.

**The agent is not in Deck.** Almost always `MC_INBOX_AGENT_ALLOWLIST`, as
above. Otherwise check the folder `$INBOX_ROOT/quill/inbox` exists and that
Deck is reading the same `INBOX_ROOT`.

**The agent started and then closed, or `boot-agents.sh` exits 3.** Exit 3
means "not ready yet", often a setup question waiting for you. Attach with
`tmux attach -t agents:quill`, answer it, then run `boot-agents.sh` again. If
you pressed Enter on the trust question it chose No and the agent exited.
Run `boot-agents.sh` again and choose Yes this time.

**The agent never said hello.** The first message is sent once, and a closed
first launch can use it up. Exit the agent's tool, delete
`$AGENTS_HOME/quill/.first-boot-done`, and run `boot-agents.sh` again.

**It says `CANNOT VERIFY` (exit 4).** There is no model tool on this machine.
Install and sign in to it, then run
`packages/base/bin/create-agent.sh --verify-only quill`.

For the full option list, see [packages/base/README.md](../packages/base/README.md).
Loading
0