Tars

A personal AI assistant that lives on your machine.
Chat from Discord or the terminal, bring the model you already pay for, and keep every memory, task, and log in one folder you can read.

Documentation · Install · Security model · Changelog

Why Tars

Most AI assistants live in someone else's cloud. Tars is a single Node.js process on hardware you
control, supervised by PM2, with its whole world under ~/.tars/: configuration, conversations,
memory, schedules, skills, extensions, and logs. Open the folder and you can see everything it knows
and everything it did.

• It answers to one person. The Discord bot only accepts messages from the preconfigured owner.
  Nothing anyone types in a chat can claim ownership.
• Bring the model you already pay for. Sign in with Claude Pro or Max, ChatGPT Plus or Pro, or
  GitHub Copilot through native OAuth. Use an API key for Anthropic, OpenAI, Google, OpenRouter, and
  every other provider in the pi model registry. Or point Tars at Ollama or any OpenAI-compatible
  endpoint.
• Memory that survives restarts. Curated workspace files are loaded into every prompt. Durable
  facts are flushed before context is compressed, and a nightly consolidation pass keeps them tidy.
• Background work you can audit. Scheduled tasks are explicit, each with its own delivery
  policy. Autonomous wakes follow a checklist you write. An empty checklist costs zero API calls.
• Extensible with plain files. Add a SKILL.md for a repeatable workflow. Enable an MCP server
  with an explicit environment allowlist. Specialized tool schemas load on demand so they never bloat
  an unrelated turn.
• Defensive defaults, documented limits. Loopback-only dashboard, SSRF-safe fetching, redacted
  logs, secret-free backups, minimal subprocess environments. Tars is not a sandbox, and the docs say
  so plainly.

Quick start

You need Node.js 22.19 or newer, npm 10.9 or newer, a Discord bot token plus your Discord user ID,
and a model provider (a subscription, an API key, or a local endpoint).

npm install -g @saccolabs/tars
tars setup     # provider sign-in, model, Discord, workspace
tars start     # launch the PM2-managed supervisor
tars status    # confirm the process and active session

Then send your bot a direct message on Discord. For a terminal-only session, stop the daemon and run
tars chat --no-discord.

What you get

Channels

• Discord. Owner-locked direct and guild messages, streaming replies, constrained attachments,
  and /stats, /quota, and /reset message commands.
• Terminal. A stateful chat TUI with token streaming that shares the same workspace and memory.
• Voice relay. A loopback JSON-lines channel so a realtime voice gateway can send turns to the
  same assistant. Tars does not handle speech itself.

Models

• Every provider in the pi model registry, plus local and custom OpenAI-compatible endpoints.
• Guided sign-in from tars setup and tars model: OAuth for Anthropic, OpenAI Codex, and GitHub
  Copilot, API keys for everyone else, or import an existing login from the standalone pi CLI.
• Models are discovered from the signed-in account and a thinking level is chosen per model.
• Optional per-role models route background and summarizer work to something cheaper.

Memory

• MEMORY.md and USER.md in the workspace are injected into the system prompt as a budget-capped
  snapshot, so Tars knows you before you say a word.
• manage_facts and manage_notes tools store durable facts and dated notes, backed by a local
  full-text index you can search with tars memory search.
• Durable memory is flushed before context compression discards turns, and a nightly "dream" pass
  consolidates the day.

Autonomy

• Scheduled tasks on a cron expression or a timestamp, with six delivery policies: notify,
  on-failure, on-change, action-required, digest, and silent.
• Pulse wakes driven by ~/.tars/workspace/HEARTBEAT.md. An empty checklist makes no API
  calls, unchanged results back off exponentially, quiet wakes stay silent, and daily budgets and
  quiet hours apply.
• Initiative modes from observe to safe-auto, limited to registered reversible repairs.
• A maintenance heartbeat handles cleanup and index sync while you are away.

Tools

• Bundled MCP extensions for memory, tasks, and public web search and fetch.
• Your own MCP servers under ~/.tars/extensions/ with strict enablement, environment allowlists,
  and bounded timeouts.
• Skills under ~/.tars/skills/ for repeatable workflows.
• Common tools stay in context. Specialized schemas load through a compact discovery catalog.

Operations

• tars doctor runs read-only health and security diagnostics. tars repair plan lists registered
  safe repairs.
• tars update stages and preflights a release before installing it, then rolls back on failure.
• tars export and tars import produce secret-free, transactional backups.
• An optional local dashboard, disabled by default and bound to loopback.

How it works

One PM2-managed supervisor serializes everything through a single active agent, so scheduled work,
background wakes, and your messages never trample each other.

Discord / terminal / voice relay
              │
              ▼
Channel manager ──► Supervisor ──► Tars engine (pi SDK) ──► model provider
                        │                  │
                        │                  └── MCP extensions, skills, memory
                        ├── active session
                        ├── cron service (explicit tasks)
                        ├── pulse service (HEARTBEAT.md wakes)
                        └── maintenance heartbeat

Everything it owns lives in one place:

~/.tars/
├── config.json      non-secret settings
├── .env             secrets, owner-readable only
├── auth.json        provider sign-ins
├── system.md        your instructions
├── workspace/       SOUL, MEMORY, USER, HEARTBEAT
├── skills/          SKILL.md packages
├── extensions/      enabled MCP servers
├── chats/           conversation history
├── data/            sessions, tasks, notes, index
└── logs/            redacted operational logs

Configuration precedence is exported environment variables, then ~/.tars/.env, then
~/.tars/config.json, then validated defaults. Intervals, context limits, and rate limits are
bounded when they load.

Security in one paragraph

Tars runs with the permissions of its operating-system user. It is not a filesystem, shell, or
network sandbox, and model output is never treated as authorization. Run it as a dedicated
least-privilege account, review every skill and extension you enable, keep the dashboard on
loopback, and keep credentials out of prompts. Redaction reduces accidental leaks; it is not
data-loss prevention. Read the full
security model before granting access to
anything sensitive.

Scope

• One active agent. Tars does not orchestrate sub-agents.
• Discord is the supported daemon channel. Terminal chat runs in the foreground and holds an
  exclusive lease on the workspace, so stop the daemon first.
• Multiple instances work with isolated TARS_HOME values, but the convenience lifecycle commands
  are not fully instance-aware.
• Scheduling polls once a minute. Do not use it for real-time or safety-critical work.

Common commands

Run tars --help for the full reference. Keep secret values out of shell history by piping them:

read -rs TARS_SECRET_VALUE
printf '%s' "$TARS_SECRET_VALUE" | tars secret set KEY
unset TARS_SECRET_VALUE

Documentation

• User documentation
• Architecture
• Development guide
• Operations guide
• Contributing

Development

npm ci
npm run ci:extensions
npm run check
npm run build
npm run test:extensions

Releases and npm publishing are managed by Release Please. Do not edit the package version by hand.
See CONTRIBUTING.md before
submitting a change.

License

MIT © Agustin Sacco