AutoTalon

English | 简体中文

AutoTalon is a local-first, long-running personal agent: it can automatically
run your programming, office, and everyday tasks on a schedule, call real tools
under sandbox and approval control, accumulate memory and experience across
tasks, and connect through gateways such as Feishu while leaving execution
traces you can inspect anytime.

Table of contents

• Why AutoTalon
• Install
• Common commands
• TUI slash commands
• Capabilities
• Security model
• Scope and limits
• Documentation
• Contributing
• License

Why AutoTalon

• A long-lived operator agent: talon tui brings conversation, sessions,
  inbox, todos, memory review, approvals, and runtime status into a single
  terminal for one agent.
• Governed tool use by default: shell, process, network, and file tools run
  under sandbox policy and approval rules, and every call is captured as trace
  events, audit logs, and rollback artifacts.
• Memory that compounds: layered memory keeps profile, project, and working
  memory, plus experience and skill references, available across tasks without
  hiding where a recall came from.
• Provider freedom: configure OpenAI-compatible, Anthropic-compatible,
  Ollama, OpenRouter, GLM, Moonshot, Qwen, xAI, Gemini, MiniMax, iFLYTEK, mock,
  or custom compatible endpoints through one provider catalog.
• Multiple entry points, one runtime: TUI, CLI, Feishu/Lark, local webhooks,
  and MCP surfaces share the same sessions, memory, and governance.
• Maintainer-grade diagnostics: replay, deterministic smoke fixtures, blind
  real-model evals, baselines, release checks, and package dry-runs ship with
  the source checkout.

Install

Requirements:

• Node.js >=22.13.0
• A provider API key for real assistant runs (skip it to try the mock provider first)

Try it in two minutes (no credentials)

Use the built-in mock provider to see the CLI and TUI work before wiring a real key:

npm install -g auto-talon
talon init --yes
talon provider setup mock
talon provider test
talon tui

Full setup (real provider)

Point AutoTalon at a real provider and open the interactive agent:

npm install -g auto-talon
talon init --yes
talon provider setup openai --api-key "$OPENAI_API_KEY"
talon provider test
talon tui

PowerShell users can set the provider key for the current session with:

$env:OPENAI_API_KEY = "your-api-key"

Windows

Native Windows is supported: the CLI, TUI, and gateways run without WSL.
./scripts/setup.ps1 builds and bootstraps a source checkout and warns if git
or ripgrep (rg) are missing from PATH. See
Windows troubleshooting for ripgrep,
Git, and PowerShell execution-policy tips.

Upgrading

Upgrading from a preview checkout that still uses the legacy thread→session
schema requires running talon doctor --fix once.

To run from source, see Contributing.

Common commands

talon tui                              # daily interactive agent surface
talon run "review the changed files"   # scriptable one-shot execution
talon continue --last                  # resume the previous task
talon trace <task_id> --summary        # inspect what the agent did
talon provider use ollama              # switch the active provider
talon schedule create "Review my inbox" --name "Daily review" --every 1d
talon gateway serve-webhook --port 7070

See the Commands reference for the full CLI/TUI
surface, including sessions, audit, memory, inbox, commitments, skills, and
gateway adapters.

TUI slash commands

Inside talon tui, slash commands drive sessions, models, memory, and scheduling:

See the Commands reference for the full slash-command list.

Capabilities

Long-term memory is off by default. Turn it on with /memory on in the TUI or
talon memory on; see docs/user/memory.md.

Security model

AutoTalon is designed for a local operator who wants an agent with real tool
access and visible guardrails.

• Local state is stored under .auto-talon/, including SQLite data, logs,
  artifacts, config, approval rules, and rollback snapshots.
• High-risk tools can require explicit approval before execution. Approval
  decisions are fingerprinted and can be scoped through persisted rules.
• Shell and filesystem access are checked against sandbox policy and project
  boundaries before execution.
• Tool calls, provider events, approvals, policy decisions, file writes, and
  rollback artifacts are recorded for later inspection.
• Feishu/Lark and webhook inputs enter through gateway adapters, so they share
  the same runtime policy instead of bypassing the local governance layer.

Read SECURITY.md before exposing gateways or running AutoTalon
against sensitive project directories.

Scope and limits

• AutoTalon requires Node.js >=22.13.0 because runtime storage uses the
  built-in node:sqlite module. Node.js 20 is not supported.
• AutoTalon is local-first and single-operator oriented. It is not a hosted
  SaaS, team control plane, or multi-tenant agent service.
• Real provider runs require user-supplied credentials. Mock and scripted smoke
  providers are for tests and diagnostics.
• v0.1.0 includes Feishu/Lark and local webhook gateway adapters. Slack,
  Telegram, Discord, voice, browser automation, image generation, and companion
  mobile/desktop apps are outside this release.

Documentation

See the Changelog for release history.

Contributing

Contributions are welcome. See CONTRIBUTING.md for developing
from source, running quality checks, and validating a release. The next-release
plan and claimable work items are in ROADMAP.md. Report issues at
the issue tracker.

License

MIT. See LICENSE.