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}references in config and MCPheaders/envvalues 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 --name --transport <stdio | sse |
npx talonctl auth-mcp <skill>:<server> |
Authorize an HTTP MCP server with OAuth |
npx talonctl add-provider --name <n> --command <c> [--context both] [--type <t>] |
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 (Codex, 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 `Codex --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:
- Codex:
Codex --version. Auth:Codex 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) Codex only (default)
b) Gemini CLI only
c) Both (recommended if both are installed)
d) OpenAI-compatible / Ollama endpoint
For each selected provider, run add-provider:
# Codex (if selected)
npx talonctl add-provider --name Codex \
--command Codex \
--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.
For an OpenAI-compatible endpoint such as local Ollama, Ollama Cloud, vLLM, or
Groq, use a unique provider name when multiple endpoints should coexist. Use
type: openai-compatible via the CLI flag so the provider name remains
distinct for persona routing and run history:
npx talonctl add-provider --name <provider-name> \
--type openai-compatible \
--command node \
--context both \
--context-window <tokens> \
--default-model <model> \
--base-url <https-or-http-base-url-ending-in-/v1> \
--provider-id <auth-provider-id> \
--enabled
If the foreground endpoint exposes /v1/responses, add --api-mode responses.
If it also supports stateful previous_response_id chaining, add
--session-mode previous_response_id. That makes Talon resume conversations
with previous_response_id so oMLX-style endpoints can reuse their
response-state chain and prefix/KV cache. Talon scopes those stored response
ids by provider and model, so testing a different model on the same provider
starts a fresh session and receives assembled prior-conversation state. Do not
use previous_response_id session mode for background-only providers, Ollama,
vLLM, Groq, or ordinary chat-completions-only endpoints.
Examples:
- Existing Ollama Cloud can remain named
openai-compatiblewithproviderId: ollama. - A separate local Mac endpoint can be named
ollama-macwith--type openai-compatible --base-url http://<mac-host>:11434/v1 --provider-id ollama-mac. - A local oMLX endpoint can be named
omlx-localwith--type openai-compatible --base-url http://<mac-host>:8000/v1 --provider-id omlx-local --context agent-runner --api-mode responses --session-mode previous_response_id.
Add matching credentials under auth.providers.<provider-id> if the endpoint
requires them. Local Ollama usually does not require an API key.
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 Codex
npx talonctl test-provider --name gemini-cli
npx talonctl test-provider --name <openai-compatible-alias>
If a test fails, troubleshoot:
- Binary not found → check the command path,
which Codexorwhich gemini - Auth failure → Codex:
Codex 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
Optional: subscription-backed sub-agents
Only discuss this when the user specifically wants small, bounded sub-agent
tasks to use an existing Claude Code or Codex subscription instead of API
credentials. It is not a foreground or background provider configuration and
does not use add-provider. Do not offer direct Codex CLI as a sub-agent model:
its agentic mode cannot yet enforce Talon's filesystem-read boundary.
First confirm that the selected CLI is installed and already authenticated as
the same OS user that runs talond, or that the official
CLAUDE_CODE_OAUTH_TOKEN is supplied for a headless subscription setup. For
Codex, first ensure Docker or rootless Podman is available on Linux/macOS, then
follow the README's managed runner login and container commands using a dedicated
Codex account; never add the user's host ~/.codex directory as a Talon mount
or start node dist/codex-runner/index.js on the Talon host. For a Linux
systemd deployment, use deploy/install-service.sh --codex-runner; it starts
the contained runner before Talon automatically on future boots. On macOS, use
the documented --restart unless-stopped container and a container runtime that
starts at login. Show the user the subagentCli, subagentSandbox, and
subagents example from the README's Subscription-backed sub-agents section. Explain the limits before
they enable it: one isolated generation per task, no Talon tools/MCP/persona
tool access, no persistent session, and no estimated API-dollar cost. Claude
Code has tools disabled. Codex runs only in the codex-runner container with
no Talon data/config mounts or Docker socket, uses ChatGPT auth only, and fails
closed on built-in tool activity. The configured sub-agent timeout aborts the
runner request before failover; maxTokens is advisory. When the Codex runner
is enabled, Talon waits for its authenticated readiness endpoint at startup and
does not start channels or dequeue work until it is ready.
There is no talonctl configuration command for subagentCli or
subagentSandbox yet, so make this narrowly-scoped manual YAML exception only
after user confirmation. Run
npx talonctl doctor --config talond.yaml after the edit, then restart the
daemon because hot reload does not rebuild the sub-agent resolver. Do not run a
live sub-agent merely to test it: that would consume the user's subscription quota.
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 - 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 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 Codex
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 authentication
For static HTTP tokens or stdio credentials, use a ${ENV_VAR} placeholder
and store the actual value in .env:
npx talonctl add-mcp --skill work-search --name internal-search --transport http \
--url https://search.example.com/mcp \
--headers 'Authorization=Bearer ${SEARCH_API_TOKEN}'
npx talonctl env-check
For OAuth, use an HTTPS resource URL, --auth oauth2, and then authorize the server:
npx talonctl add-mcp --skill work-search --name glean --transport http \
--url https://search.example.com/mcp --auth oauth2
npx talonctl auth-mcp work-search:glean
If the authorization server has no Dynamic Client Registration endpoint,
provide --client-id-env and, if required, --client-secret-env when adding
the server, and pin the issuer with --authorization-server-issuer https://<issuer>.
--token-endpoint-auth-method accepts client_secret_post or
client_secret_basic. On OAuth-backed runs, native shell/filesystem tools are
disabled while Talon tools and configured MCP servers remain available;
Codex CLI is rejected because it cannot disable those built-ins. Request only
needed scopes with --scopes; Talon does not request all provider-advertised
scopes automatically. Environment checks report variable names and status,
not values. Talon expands MCP header/stdIO env references once and rejects
resulting values that still look like provider environment-variable syntax.
Re-run auth-mcp after changing the MCP resource URL or configured
scopes; cached credentials are bound to both. For Docker Desktop, use auth-mcp ... --docker; see the Docker
setup skill for the host-local callback requirements.
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 and MCPheaders/envfields. - 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.