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 aprompts/directory for prompt fragments.
Example:
# 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 loginor valid Anthropic API key. - Gemini CLI:
gemini --version. Auth: rungeminionce interactively for OAuth, or setGEMINI_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:
# 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?"
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)
npx talonctl set-default-provider --name <choice> --context background
Test each configured provider:
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 claudeorwhich gemini - Auth failure → Claude:
claude auth login. Gemini: rungeminiinteractively 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 |
/add-whatsapp |
|
/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?"
- Accept a name (suggest "assistant")
- Run:
npx talonctl add-persona --name <name> - Ask these questions one at a time:
- "What should {name} do?" (purpose)
- "What tone?" (professional/casual/technical/friendly)
- "Any specific constraints?" (optional)
- Generate a system prompt from the answers
- Show it to the user for review
- Write the approved prompt to
personas/{name}/system.md, starting with YAML frontmatter containing a one-linedescription:(what tasks to delegate to this persona); other personas use it to choosepersona_sendtargets - Ask which channels to bind:
- Run:
npx talonctl list-channelsto show options - For each selected:
npx talonctl bind --persona <name> --channel <channel>
- Run:
Ask: "Add another persona?" Loop until done.
Step 5b: Capability configuration
After creating a persona, show what capabilities it has and what's available.
- Run:
npx talonctl set-capabilities --persona <name> --show - Run:
npx talonctl list-capabilities - Explain: "Your persona was created with sensible defaults: memory access, HTTP requests, and schedule management. Here are all available capabilities."
- 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 grantspersona_list,persona_task_statusandpersona_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:*"— plusvisionin that persona'ssubagentslist; 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:
visionlisted under the persona'ssubagentskey intalond.yaml. There is notalonctlflag for persona sub-agent assignment, so edit the config.subagent.invoke— the existing capability on the invoke tool:
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:
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
visionsub-agent; the main persona stays text-only. - Only
anthropic/openai/google/ollamamay 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) andmaxNormalizedBytes(default 3.75 MB; lower it if the vision provider has a smaller per-image limit — oversized images are re-encoded smaller automatically). Anyimageschange needs a daemon restart;talonctl reloadkeeps the running values. Seeconfig/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):
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:
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 7am0 18 * * 1-5— weekdays at 6pm0 16 * * 5— Friday at 4pm0 19 * * 0— Sunday at 7pm0 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:
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:
sudo ./deploy/install-service.sh --user $(whoami) --dir $(pwd)
Step 12: Summary
Run these to build the summary:
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:
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:
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.0disables excerpting for that server only. Omitted → provider-leveltoolOutputCapor 4 000. Precedence: server > provider > 4 000; provider-level0disables 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. 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:
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
- Never write actual secrets. Only
${ENV_VAR}placeholders in config files. - Use talonctl commands for all config mutations. Exceptions: system prompt files, task prompt files, and
.env. Narrow exception: the two numeric keystimeoutMs/toolOutputCapunderconfigin an existing MCP server JSON (skills/<skill>/mcp/<server>.json) may be edited manually — no other manual MCP JSON or config edits. - One question per message. Do not batch questions.
- Show command output. Let the user see what happened.
- Don't start the daemon. Setup only. The user starts it themselves.
- Validate at the end. Always run doctor, env-check, and test-provider before declaring setup complete.
- Test providers. After any provider change, run
test-providerto verify.