# Tentacles

Tentacles are the core abstraction in Octogent.

## What a tentacle is

A tentacle is a folder under `.octogent/tentacles/<tentacle-id>/` that stores agent-readable markdown files.

The minimum useful files are:

- `CONTEXT.md`
- `todo.md`

Additional markdown files are allowed and are surfaced as tentacle vault files in the app.

The important part is that the folder is agent-facing. It is the durable context that a terminal agent can read, edit, and hand off to another terminal.

## How Deck reads a tentacle

Deck does not maintain a separate database copy of the tentacle context. It scans `.octogent/tentacles/` and derives most of the view from files:

- a folder is considered a tentacle only when it contains `CONTEXT.md`
- the first `# Heading` in `CONTEXT.md` becomes the display name
- the first non-empty paragraph after that heading becomes the description
- every other `.md` file becomes a vault file, with `todo.md` sorted first
- checkbox lines in `todo.md` become progress and worker inputs

Deck-specific metadata such as color, status, octopus appearance, paths, and tags lives separately in runtime state. That keeps UI preferences out of the agent-facing markdown files.

## What a tentacle is for

Use a tentacle when one slice of the codebase or one track of work needs its own local operating context.

Examples:

- API runtime
- frontend shell
- prompt system
- monitor integration
- release work

## What goes in `CONTEXT.md`

`CONTEXT.md` should explain:

- what this area owns
- the important files or directories
- what already exists
- constraints and edge cases
- what not to break
- any Claude Code skills that are especially useful for this tentacle, when relevant

The first heading and first non-empty paragraph are runtime-significant. Keep them stable and useful because they become the name and description shown in Deck, Canvas, prompt summaries, and terminal creation flows.

When a tentacle has suggested Claude Code skills, Octogent appends a managed block at the bottom of `CONTEXT.md`:

```md
<!-- octogent:suggested-skills:start -->
## Suggested Skills

You can use these skills if you need to.

- `skill-name`
<!-- octogent:suggested-skills:end -->
```

The managed block is rewritten by the API when suggested skills change. Put human-authored architecture notes outside that block.

## What goes in `todo.md`

`todo.md` should contain markdown checkbox items:

```md
# Todo

- [ ] add request validation for monitor config
- [ ] cover the invalid payload case in tests
- [x] wire the route into the request handler
```

The runtime parses checkbox lines and computes progress.

Only lines that match `- [ ] text` or `- [x] text` are treated as todo items. Their order matters because swarm creation uses the parsed item index when it creates worker terminal IDs such as `<tentacle-id>-swarm-0`.

When the UI toggles, edits, adds, or deletes todos, it rewrites `todo.md`. There is no hidden todo store.

## Tentacles and delegation

The point of a tentacle is not only documentation. It is operational context.

A worker attached to a tentacle can:

- read local notes first
- stay scoped to that area
- use the todo list as a work queue
- hand work to child agents without rebuilding context from scratch

When a todo item is solved from Deck, Octogent reads the item text, resolves a worker prompt template, and creates a terminal attached to the same tentacle. For swarm runs, incomplete todo items become workers, and larger swarms get a parent coordinator terminal that supervises completion.

## Tentacles and worktrees

Tentacles are not the same thing as worktrees.

- a tentacle is a context folder
- a worktree is an isolated git checkout for a terminal

You can use a tentacle with shared workspace terminals or worktree terminals.

In shared mode, all terminals operate in the main workspace, so the context boundary is social and procedural. In worktree mode, each terminal can get a separate checkout under `.octogent/worktrees/`, but it still reads the same tentacle folder for instructions and todos.

## Failure boundaries

- deleting a tentacle removes its agent-facing files, but terminal records are separate runtime state
- restarting the API preserves terminal metadata and transcripts but not live PTYs
- channel messages do not persist, so durable handoffs belong in tentacle markdown
- worktree branches are tied to worktree-backed terminals, not to the tentacle folder itself