> ## Documentation Index
> Fetch the complete documentation index at: https://stampede.autonomousorganizations.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Persons

> Create named assistants with their own purpose, model and policy, address them from the console, and watch their runs.

One installation of Stampede can run several assistants side by side, each with its own job and limits. Each of these assistants is a person: a durable identity with a name, a purpose, an optional private identity text, a model profile and a standing policy that bounds what it may do when nobody is watching.

## What a person holds

| Part | What it is |
| - | - |
| Name | A handle of 1 to 64 ASCII letters, digits, `-` or `_`. It is stored in lowercase, so `Analyst`, `analyst` and `@ANALYST` are the same person. The name cannot be changed. |
| Purpose | One line, up to 512 bytes, that tells the model what this person is for. |
| Identity | Optional private text, up to 16 KiB, added to the person's system prompt. It is stored encrypted. |
| Model | A profile name from `~/.stampede/config.toml`. Without one the person runs on the default profile. |
| Policy | The tools the person may use, the programs it may run, and how far its requests may be passed on. See [Presets and permissions](https://stampede.autonomousorganizations.ai/persons/presets.md). |

A person also has its own project memory, goals, skills, sessions and mailbox. The operator's user memory, secrets, workspace and run list are shared by every person on the home.

Persons are cooperating assistants under one operating system account. They are not separate users and not sandboxes: you, as the operator, can read every inbox and every run.

On a fresh home the only person is the built-in `main`, which is the active and default identity. The name `main` is reserved.

## Creating a person

```bash theme={null}
stampede person create editor --purpose "Reviews prose for clarity; never edits files" --policy research
stampede person create builder --purpose "Implements small changes in the workspace" --policy builder
stampede person create lead --purpose "Coordinates the work between persons"
```

`lead` has no `--policy`, so it is free: it may use every tool and run every program the home allows. The command prints one line saying so:

```text theme={null}
person lead has no preset: it may use every tool and run every program this home allows (free)
```

`stampede person create` with no name asks for the name, purpose, identity and model on the terminal and creates a free person. In a script, always pass the name.

| Flag | Meaning |
| - | - |
| `--purpose TEXT` | The person's purpose. |
| `--identity-file PATH` | A file whose text becomes the private identity. It must be a regular file owned by you with mode `0600`, at most 16 KiB. Keep it outside the directories the model can read. |
| `--model PROFILE` | A model profile name from `config.toml`. |
| `--policy PRESET` | One of `research`, `writer`, `reviewer`, `coordinator`, `builder`, `maintainer`, `free`. `operator` is accepted as the old name of `free`. |
| `--allow-tool NAME` | Adds one exact tool name to a preset, a built-in tool or an MCP tool such as `tracker__create_issue`. Repeatable. |
| `--allow-command PROGRAM` | Adds one program to the preset's program list. Repeatable. |
| `--max-hops N` | How many times a request may be passed on to another person before it is refused, from 1 to 256. The default is 256. |
| `--operation-id HEX` | A 64-character hex id that makes a retried create idempotent. Reusing it for different content is refused. |

`--allow-tool` and `--allow-command` need a preset. A free person is already unrestricted and refuses additions, and a `maintainer` refuses `--allow-command` because it already runs any program:

```bash theme={null}
stampede person create notes --policy research --allow-tool weather__forecast
stampede person policy builder builder --allow-command make
```

To write the identity file safely:

```bash theme={null}
mkdir -p ~/stampede-private && chmod 700 ~/stampede-private
printf '%s\n' 'You are the release assistant. Verify every claim against the repository.' > ~/stampede-private/release.txt
chmod 600 ~/stampede-private/release.txt
stampede person create release --purpose "Release checks" --identity-file ~/stampede-private/release.txt --policy reviewer
```

## Listing and inspecting persons

```bash theme={null}
stampede person list
stampede person show builder
```

`person list` prints one line per person with its policy label in parentheses: the preset name, `free`, or `custom` for a list that matches no preset. A leading `*` marks the default person.

```text theme={null}
* main (research)
  builder (builder)
  editor (research)
  lead (free)
```

`person show` prints the full record, the decrypted identity text included, and warns first. It also prints the effective program list.

## Changing a person

| Command | What it changes |
| - | - |
| `stampede person edit NAME --purpose TEXT` | The purpose. `--clear-purpose` removes it. |
| `stampede person edit NAME --identity-file PATH` | The identity text. `--clear-identity` removes it. |
| `stampede person edit NAME --model PROFILE` | The model profile. `--clear-model` returns to the default. |
| `stampede person policy NAME PRESET [options]` | Replaces the policy. It takes the same `--allow-tool`, `--allow-command`, `--max-hops` and `--operation-id` options as `create`. |
| `stampede person use NAME` | Sets the default person for processes started later. |

Edits and policy changes apply to runs started afterwards. A run already started keeps the profile and the grant it began with, and a run resumed after a crash is checked against the current policy, so narrowing a policy can stop an old unattended grant.

```bash theme={null}
stampede person edit builder --model fast --purpose "Implements and tests small changes"
stampede person policy editor writer
```

## Addressing a person from the console

In `stampede tui` or `stampede chat`, a line that starts with `@name` queues a request for that person. The person runs it in the background while you keep typing, and the console prints its progress lines.

```text theme={null}
@builder create notes/summary.md with a three-line summary of README.md, then ask editor to review it and apply the review
```

A person is bounded by its policy even when you address it. `@editor delete notes/summary.md` is refused with a refusal line in the console, because the `research` preset has no write tool, and the file stays.

To work as a person yourself, start a new process for it:

```bash theme={null}
stampede --person builder tui
STAMPEDE_PERSON=builder stampede chat
stampede --person builder agent "run the test suite and report failures"
```

`--person` wins over `STAMPEDE_PERSON`, which wins over the default set with `person use`. A process keeps the person it started with. In such a session you are at the keyboard, so calls are decided by your own tool policy and your answers. The person's policy binds its unattended work: `@name` requests, requests from other persons, schedule fires, webhook deliveries and gateway requests.

Every person command also works inside the console with `/person` in place of `stampede person`, for example `/person list` or `/person policy editor writer`. `/person NAME` prints how to start a conversation as that person. See [Console](https://stampede.autonomousorganizations.ai/start/console.md).

## Mail and task rooms

Persons send each other durable mail with `stampede person send` and `send_message`, and work that needs several persons runs as a task room. Both are described in [Mail and task rooms](https://stampede.autonomousorganizations.ai/teamwork/mail-and-task-rooms.md).

## Observing a person's runs

```bash theme={null}
stampede person runs builder
stampede runs list --person builder
stampede runs show RUN_ID
stampede runs show RUN_ID --tokens
stampede person goals builder
```

`person runs` lists the runs recorded for that person, each with its model and status. `runs show` prints a run's events with one line per tool call: the tool, its outcome, and the gate that refused it when it was refused, followed by a count of tool calls by outcome. Prompts, arguments and outputs stay encrypted. `--tokens` adds one line per model call with token counts and cost.

`person runs` does not say who drove a run, so a session you ran with `--person` is listed beside the person's own work. In `runs show`, the first event's owner label is `operator` for a session you drove and `delegated` for work the person ran on its own.

Inside the console, `/person runs` and `/person goals` with no name use the active person.

## Per-person settings

Some settings of a person live in `~/.stampede/config.toml`, in a `[persons.NAME]` table:

```toml theme={null}
[persons.analyst]
project_instructions = false
auto_load = ["house-style"]

[persons.main]
auto_load = ["review-release-state"]
```

| Key | Default | Meaning |
| - | - | - |
| `project_instructions` | `true` | `false` loads no `AGENTS.md`, `CLAUDE.md` or `STAMPEDE.md` in this person's runs. See [Project instructions](https://stampede.autonomousorganizations.ai/persons/project-instructions.md). |
| `auto_load` | `[]` | Skill names pinned into every model request of this person's runs. See [Skills](https://stampede.autonomousorganizations.ai/persons/skills.md). |

Table names are compared without case. `[persons.main]` applies to your own runs as the operator. A table whose name matches no person changes nothing, and any other key in the table makes the file fail to load. A change applies to sessions and runs started after it. The full list of keys is in [Configuration](https://stampede.autonomousorganizations.ai/reference/configuration.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.