# Talon.setup

> Use when setting up Talon for the first time, adding channels or personas to an existing config, or running validation. Also use when the user says "configure talon", "add a channel", "add a persona", "add provider", "set up the daemon", "add schedule", or "configure providers".

- Skill: `ivo-toby/talon-setup-2` (Agent Skill)
- Install (CLI): `npx get-skill add ivo-toby/talon-setup-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ivo-toby/talon-setup-2/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: ivo-toby (https://skillmd.com/u/ivo-toby)
- Updated: 2026-11-12
- Page: https://skillmd.com/skills/ivo-toby/talon-setup-2

---


# Talon setup skill

Guide the user through setting up and configuring Talon interactively. This is a
conversational wizard. Ask one question at a time, act on the answer, move on.

## Core principles

- **One question at a time.** Never dump a wall of questions.
- **Detect state first.** Skip steps that are already done.
- **Use talonctl commands.** Never edit talond.yaml directly except system prompts and task prompts.
- **No secrets.** Never ask for or write actual tokens. Use `${ENV_VAR}` placeholders only.
- **Show what you do.** When running commands, show the output.

## Available talonctl commands

All config mutations go through these commands:

| Command | Purpose |
|---------|---------|
| `npx talonctl setup` | Bootstrap (dirs, config, migrations) |
| `npx talonctl add-channel --name <n> --type <t>` | Add a channel |
| `npx talonctl add-persona --name <n>` | Scaffold persona + add to config |
| `npx talonctl add-skill --name <n> --persona <p> [--format <fmt>]` | Add a skill to a persona |
| `npx talonctl bind --persona <p> --channel <c>` | Bind persona to channel |
| `npx talonctl unbind --persona <p> --channel <c>` | Remove binding |
| `npx talonctl add-mcp --skill <s> --name <n> --transport stdio --command <c>` | Add MCP server |
| `npx talonctl add-provider --name <n> --command <c> [--context both]` | Add a provider |
| `npx talonctl set-default-provider --name <n> --context <ctx>` | Set default provider |
| `npx talonctl test-provider --name <n>` | Test a provider works |
| `npx talonctl list-providers` | Show all providers |
| `npx talonctl list-channels` | Show channels |
| `npx talonctl list-personas` | Show personas |
| `npx talonctl list-skills` | Show skills |
| `npx talonctl list-schedules` | Show scheduled tasks |
| `npx talonctl add-schedule --persona <p> --channel <c> --cron <expr> --label <l> --prompt <text>` | Add scheduled task |
| `npx talonctl remove-schedule <id>` | Remove a scheduled task |
| `npx talonctl list-capabilities` | Show all available capability labels |
| `npx talonctl set-capabilities --persona <p> --allow <labels>` | Set persona capabilities |
| `npx talonctl set-capabilities --persona <p> --add <labels>` | Add capabilities to persona |
| `npx talonctl set-capabilities --persona <p> --remove <labels>` | Remove capabilities from persona |
| `npx talonctl set-capabilities --persona <p> --show` | Show persona's current capabilities |
| `npx talonctl env-check` | Audit env var placeholders |
| `npx talonctl config-show` | Show effective config (secrets masked) |
| `npx talonctl remove-channel --name <n>` | Remove a channel |
| `npx talonctl remove-persona --name <n>` | Remove a persona |
| `npx talonctl migrate` | Run database migrations |
| `npx talonctl doctor` | Validate configuration |

## State detection

Before starting, check the current state:

```
Check these files/directories:
- talond.yaml              → config exists?
- node_modules/            → dependencies installed?
- dist/                    → project built?
- data/                    → data directory exists?
- data/talond.sqlite       → database initialized?
- .env                     → env file with secrets?
```

### Entry points

| State | Action |
|-------|--------|
| No `talond.yaml` | Full flow from step 1 |
| Config exists, no providers configured | Skip to provider setup |
| Config exists, no channels | Skip to channel configuration |
| Config exists, has channels and personas | Show menu |

### Returning user menu

If setup is already complete, present:

```
What would you like to do?
  a) Add or configure a provider (Claude, Gemini)
  b) Add a channel
  c) Add a persona
  d) Add a skill to a persona
  e) Add or manage scheduled tasks
  f) Bind/unbind persona to channel
  g) Run validation (doctor)
  h) Show current config summary
  i) Test a provider
  j) Check environment variables
```

## Skill formats

When adding a skill, choose a format with `--format`:

- **SKILL.md** (`--format skillmd`, recommended for new skills): Single markdown file with YAML frontmatter for metadata and markdown body for instructions. No separate prompts directory.
- **skill.yaml** (`--format yaml`, default/legacy): Separate YAML manifest file plus a `prompts/` directory for prompt fragments.

Example:
```bash
# New style (recommended)
npx talonctl add-skill --name my-skill --persona assistant --format skillmd

# Legacy style (default if --format is omitted)
npx talonctl add-skill --name my-skill --persona assistant
```

## Full setup flow

### Step 1: Prerequisites

Check each prerequisite. Report status. Fix what can be fixed automatically.

```
1. Node.js >= 22          → check `node --version`
2. Dependencies installed → check node_modules/, run `npm install` if not
3. Project built          → check dist/, run `npm run build` if not
4. AI providers installed → check `claude --version` and/or `gemini --version`
```

For provider binaries not on PATH, ask for the full path (e.g. `/home/user/.npm-global/bin/gemini`).

At least one provider must be installed and authenticated. Check both:

- **Claude Code**: `claude --version`. Auth: `claude auth login` or valid Anthropic API key.
- **Gemini CLI**: `gemini --version`. Auth: run `gemini` once interactively for OAuth, or set `GEMINI_API_KEY`.

If neither is installed, stop and explain how to install at least one.

### Step 2: Bootstrap

Skip if `talond.yaml` already exists.

Run: `npx talonctl setup`

This creates directories, generates default config, runs migrations, validates.

### Step 3: Provider configuration

This step configures which AI providers Talon uses for interactive conversations and background tasks.

Ask: **"Which AI providers do you want to use?"**

```
a) Claude Code only (default)
b) Gemini CLI only
c) Both (recommended if both are installed)
```

For each selected provider, run `add-provider`:

```bash
# Claude (if selected)
npx talonctl add-provider --name claude-code \
  --command claude \
  --context both \
  --context-window 200000 \
  --threshold-ratio 0.5 \
  --enabled

# Gemini (if selected)
npx talonctl add-provider --name gemini-cli \
  --command <path-to-gemini> \
  --context both \
  --context-window 1000000 \
  --threshold-ratio 0.8 \
  --enabled
```

For Gemini, ask: **"Which Gemini model? (default: gemini-2.5-pro)"**

Available models: gemini-3.1-pro-preview, gemini-3-flash-preview, gemini-2.5-pro, gemini-2.5-flash, gemini-2.5-flash-lite.

If a model is specified, add `--default-model <model>` to the add-provider command.

If both providers are configured, ask: **"Which should be the default for conversations?"**

```bash
npx talonctl set-default-provider --name <choice> --context agent-runner
```

Then: **"And for background tasks?"** (explain: background tasks run async, cheaper/faster models work well here)

```bash
npx talonctl set-default-provider --name <choice> --context background
```

Test each configured provider:

```bash
npx talonctl test-provider --name claude-code
npx talonctl test-provider --name gemini-cli
```

If a test fails, troubleshoot:
- Binary not found → check the command path, `which claude` or `which gemini`
- Auth failure → Claude: `claude auth login`. Gemini: run `gemini` interactively once for OAuth.
- JSON parse failure → Gemini CLI version too old, see https://github.com/google-gemini/gemini-cli for upgrade instructions

### Step 4: Channel configuration

Ask: **"Which channel do you want to connect first?"**

```
a) Telegram
b) Slack
c) Discord
d) WhatsApp
e) Email
f) Terminal (for CLI chat)
g) Skip for now
```

Invoke the matching per-channel skill for the full setup walkthrough:

| Channel | Skill to invoke |
|---------|----------------|
| Telegram | `/add-telegram` |
| Slack | `/add-slack` |
| Discord | `/add-discord` |
| WhatsApp | `/add-whatsapp` |
| Email | `/add-email` |
| Terminal | `/add-terminal` |

Each skill handles: bot/app creation, credentials, config, env vars, verification, and troubleshooting.

Ask: **"Add another channel?"** Loop until done.

### Step 5: Persona configuration

Ask: **"Let's create a persona. What should this agent be called?"**

1. Accept a name (suggest "assistant")
2. Run: `npx talonctl add-persona --name <name>`
3. Ask these questions one at a time:
   - **"What should {name} do?"** (purpose)
   - **"What tone?"** (professional/casual/technical/friendly)
   - **"Any specific constraints?"** (optional)
4. Generate a system prompt from the answers
5. Show it to the user for review
6. Write the approved prompt to `personas/{name}/system.md`, starting with YAML
   frontmatter containing a one-line `description:` (what tasks to delegate to
   this persona); other personas use it to choose `persona_send` targets
7. Ask which channels to bind:
   - Run: `npx talonctl list-channels` to show options
   - For each selected: `npx talonctl bind --persona <name> --channel <channel>`

Ask: **"Add another persona?"** Loop until done.

### Step 5b: Capability configuration

After creating a persona, show what capabilities it has and what's available.

1. Run: `npx talonctl set-capabilities --persona <name> --show`
2. Run: `npx talonctl list-capabilities`
3. Explain: "Your persona was created with sensible defaults: memory access, HTTP requests,
   and schedule management. Here are all available capabilities."
4. Ask: **"Want to adjust capabilities for {name}?"**

If yes, help the user decide which to add or remove:

- For agents that should message other channels: `npx talonctl set-capabilities --persona <name> --add "channel.send:*"`
- For agents that need database access: `npx talonctl set-capabilities --persona <name> --add "db.query:own"`
- For agents that delegate to other personas: `npx talonctl set-capabilities --persona <name> --add "persona.send:<target-persona>"` (one label per allowed target, so the persona can only delegate to those; `persona.send:*` allows any persona). The same label also grants `persona_list`, `persona_task_status` and `persona_task_cancel`. An unknown target name only logs a warning at startup
- For agents that run background tasks: `npx talonctl set-capabilities --persona <name> --add "subagent.background"`
- For agents that invoke sub-agents: `npx talonctl set-capabilities --persona <name> --add "subagent.invoke"`
- For agents that should discuss uploaded images: `npx talonctl set-capabilities --persona <name> --add "subagent.invoke:*"` — plus `vision` in that persona's `subagents` list; see **Image handling** below

Repeat for each persona.

**Image handling** is a two-part Inspection setup plus one independent lookup
grant. None of it happens automatically on upgrade.

An **Inspection** needs exactly two things — the shipped `vision` manifest declares
`requiredCapabilities: []`, so no image capability is involved:

1. `vision` listed under the persona's `subagents` key in `talond.yaml`. There is
   no `talonctl` flag for persona sub-agent assignment, so edit the config.
2. `subagent.invoke` — the existing capability on the invoke tool:

```bash
npx talonctl set-capabilities --persona <name> --add "subagent.invoke:*"
```

`image.read:thread` is a **separate** permission, not part of an Inspection. It
exposes `image_lookup`, the model-free reader for the thread's Images and saved
Findings; it needs no vision assignment, never calls a model, and downloads
nothing, so it is safe to grant where you would not grant vision. Recommended (so
the persona can re-read an existing Finding instead of paying for a repeat
Inspection), but optional:

```bash
npx talonctl set-capabilities --persona <name> --add "image.read:thread"
```

Uploads are ingested and described regardless of all of the above. When confirming
setup, mention that:

- Pixels go only to the `vision` sub-agent; the main persona stays text-only.
- Only `anthropic` / `openai` / `google` / `ollama` may be in the vision chain;
  a text-only override is rejected at config load, not skipped.
- Normalized image files are deleted after `images.retentionHours` (default 24h),
  but Image records, GPS/EXIF and Findings persist until separately deleted and
  may appear in replies — including in admitted group chats.
- Inspections work from normal messages and scheduled tasks, not from background
  agents (those are refused before any model is called).
- The defaults in the `images:` block suit most setups. If the operator wants to
  tune it: `maxInputPixels` (default 100 MP, a decompression-bomb guard, max
  ~268 MP) and `maxNormalizedBytes` (default 3.75 MB; lower it if the vision
  provider has a smaller per-image limit — oversized images are re-encoded smaller
  automatically). Any `images` change needs a daemon restart; `talonctl reload`
  keeps the running values. See `config/talond.example.yaml`.
- On a sequential connector an image-bearing message delays other traffic on that
  connector — Telegram polling is the example, waiting up to ~120 seconds (a fixed
  60-second remote-fetch budget plus a separate 60-second normalization deadline).
  WhatsApp handles each chat in order but chats in parallel, so a text sent right
  after a photo waits for that photo while other chats keep flowing; a downloaded
  WhatsApp image still carries the same per-message 60-second fetch + 60-second
  normalization budgets. Email does no remote fetch — its bytes
  already arrived with the message — so only the shared 60-second normalization
  deadline applies there.

### Step 6: Scheduled tasks

Ask: **"Do you want to set up scheduled tasks?"**

Explain what they are: the agent runs a task prompt on a cron schedule and sends results to a channel. This makes the agent proactive instead of reactive.

Recommend starting with memory grooming (required for long-term health):

```bash
npx talonctl add-schedule \
  --persona assistant \
  --channel <primary-channel> \
  --cron "0 3 */2 * *" \
  --label "Memory grooming" \
  --prompt "Run the memory-grooming task prompt"
```

Explain: without memory grooming, the agent's stored memory fills up with stale and duplicate entries. Every 2-3 days at a quiet hour is the recommended cadence.

Then offer other common schedules:

```
Suggested schedules (optional):
  a) Morning briefing (weekdays 7am) — calendar, email, Jira, GitHub summary
  b) End-of-day summary (weekdays 6pm) — recap and tomorrow preview
  c) Weekly review (Friday 4pm) — stale tickets, forgotten follow-ups
  d) Week planning (Sunday 7pm) — upcoming week overview
  e) Custom schedule
  f) Done, skip the rest
```

For each selected, the user needs a task prompt file at `personas/<name>/prompts/<prompt-name>.md`. Either use the defaults that ship with the assistant persona or help the user write one.

Create each schedule with:

```bash
npx talonctl add-schedule \
  --persona <persona> \
  --channel <channel> \
  --cron "<expression>" \
  --label "<label>" \
  --prompt "Run the <prompt-name> task prompt"
```

Common cron expressions for reference:
- `0 7 * * 1-5` — weekdays at 7am
- `0 18 * * 1-5` — weekdays at 6pm
- `0 16 * * 5` — Friday at 4pm
- `0 19 * * 0` — Sunday at 7pm
- `0 3 */2 * *` — every 2 days at 3am

### Step 7: Database setup

Run: `npx talonctl migrate --config talond.yaml`

### Step 8: Validation

Run: `npx talonctl doctor --config talond.yaml`

For failures, provide specific remediation steps.

### Step 9: Environment check

Run: `npx talonctl env-check`

Show which env vars are missing. Tell the user to add them to `.env`.

### Step 10: Provider verification

Test every configured provider one more time:

```bash
npx talonctl test-provider --name claude-code
npx talonctl test-provider --name gemini-cli
```

Only declare setup complete if at least one provider passes.

### Step 11: Systemd service (Linux only)

Ask: **"Want to install talond as a systemd service?"**

If yes, tell the user to run:
```bash
sudo ./deploy/install-service.sh --user $(whoami) --dir $(pwd)
```

### Step 12: Summary

Run these to build the summary:
```bash
npx talonctl list-providers
npx talonctl list-channels
npx talonctl list-personas
npx talonctl list-schedules
npx talonctl env-check
```

Print results and instructions to start the daemon:

```bash
node dist/index.js          # foreground with logs
# or if systemd service is installed:
sudo systemctl start talond
```

## MCP request timeout and tool-output cap

When a persona's MCP server returns large results or makes slow calls, set
per-server limits to keep the agent's context under control. Both keys live
under `config` in the skill's MCP JSON (`skills/<skill>/mcp/<server>.json`):
add `"timeoutMs": <integer ≥ 1000>` and `"toolOutputCap": <integer ≥ 0>`,
and `talonctl add-mcp` accepts the same values as `--timeout-ms` /
`--tool-output-cap` flags:

```bash
npx talonctl add-mcp --skill work-search --name glean --transport http \
  --url https://search.example.com/mcp --auth oauth2 \
  --timeout-ms 180000 --tool-output-cap 12000
```

- `timeoutMs` (integer ≥ 1000): per-MCP-request timeout. Omitted → Mastra's
  60 000 ms default. The outer query timeout still wins.
- `toolOutputCap` (integer ≥ 0): caps a tool result before it enters message
  history. `0` disables excerpting for that server only. Omitted →
  provider-level `toolOutputCap` or 4 000. Precedence: server > provider >
  4 000; provider-level `0` disables only the fallback — an explicit positive
  per-server cap still applies.

Provider compatibility: only the Mastra / OpenAI-compatible provider honors
these limits; native Claude, Gemini, and Codex CLI runs omit the metadata, so
the limits have no effect there. The caps bound MCP model-history injection,
not network bytes: when any effective MCP cap is positive, MCP results (also
zero-cap servers) stay in a run-local in-memory store retrievable via
`fetch_tool_output` in up to 8 000 content-character slices (framing
additional) when available — a discovered MCP tool that already owns that
reserved name takes it and the synthetic recovery is skipped; with all
effective MCP caps at `0` no wrapper/recovery is injected. Built-in
file/shell tools are unchanged. For an existing server,
edit only the two numeric keys under `config` in the JSON file directly
(preserving name/URL/transport/headers/env/auth) — `add-mcp` rejects
duplicate names.

## Shared memory between agents

Talon supports shared memory between personas using the [Anthropic Memory MCP server](https://github.com/anthropics/memory). This is a knowledge graph stored in a single JSON file. When multiple personas use the same file, they share knowledge automatically.

How to set it up: for each persona that should share memory, add the memory MCP server to one of its skills:

```bash
npx talonctl add-mcp --skill <skill-name> --name memory \
  --transport stdio \
  --command npx \
  --args "-y @anthropic-ai/memory --memory-path data/shared-memory.json"
```

All personas point to the same `--memory-path`. Use `data/shared-memory.json` as the default location.

When to suggest this: when the user has multiple personas and asks about sharing context between them. Don't suggest it proactively during initial setup.

## Rules

1. **Never write actual secrets.** Only `${ENV_VAR}` placeholders in config files.
2. **Use talonctl commands for all config mutations.** Exceptions: system prompt files, task prompt files, and `.env`. Narrow exception: the two numeric keys `timeoutMs` / `toolOutputCap` under `config` in an existing MCP server JSON (`skills/<skill>/mcp/<server>.json`) may be edited manually — no other manual MCP JSON or config edits.
3. **One question per message.** Do not batch questions.
4. **Show command output.** Let the user see what happened.
5. **Don't start the daemon.** Setup only. The user starts it themselves.
6. **Validate at the end.** Always run doctor, env-check, and test-provider before declaring setup complete.
7. **Test providers.** After any provider change, run `test-provider` to verify.

