tars

README

TARS

TARS is a self-hosted AI agent runtime.

A single Go binary that runs on your machine and gives you: an interactive chat with durable memory, parallel sub-agents with model tier routing, background watchdog and nightly maintenance, scheduled jobs, and multi-channel I/O (console, Telegram, webhooks) — all configurable via YAML and extensible via skills, plugins, and MCP servers.

Comparison

	OpenClaw	Hermes Agent	TARS
Language	TypeScript	Python	Go (single binary)
Sub-agents	ACP + subagent runtimes, push-based completion, Docker sandbox	ThreadPoolExecutor (max 3), ephemeral prompt, credential override	Agent Runtime executor with per-task model tier, allowlist policy, depth control
Model routing	Per-agent model override	Per-child provider/model override, MoA (4 frontier models)	3-tier named bundles (heavy/standard/light) with role→tier config mapping
Memory	Session transcripts	Honcho/Holographic plugin hooks	Durable Markdown memory + semantic search + experience extraction + nightly reflection
Background	None	None	Pulse watchdog (1-min) + Reflection nightly batch
Scheduling	None	None	Session-bound cron jobs with audit logs
Channels	CLI	CLI + Agent Runtime API	Console + Telegram + webhooks
Context mgmt	Per-session	ContextCompressor (50% threshold, protect-last-N)	Structured compaction with identifier preservation + light-tier LLM summary
Extensibility	Built-in tools	Toolsets (terminal, file, web, delegation)	Skills + Plugins + MCP servers + Skill Hub registry

Key Features

Chat + Memory

The primary interface. Browser-based console at http://127.0.0.1:43180/console.

• Multi-session chat with full LLM tool-calling loops
• @ file and directory mentions from the session Files roots for explicit context injection
• / command autocomplete for built-in chat actions and explicit user-invocable skill selection
• /config opens advanced per-session tool and skill policy controls when a selected session needs explicit overrides
• Files workspaces include an embedded shell at the selected root or browsed subdirectory, plus a macOS Terminal fallback
• Durable memory: MEMORY.md, experiences, daily logs, semantic embeddings
• Editable memory assets and semantic recall through the console/API
• Structured transcript compaction preserving identifiers and recent context
• System prompt customization via USER.md, IDENTITY.md, AGENTS.md, TOOLS.md

Sub-Agent Orchestration

Spawn read-only agents for research, planning, and specialized tasks:

# workspace/agents/explorer/AGENT.md
---
name: explorer
tier: light
tools_allow: [read_file, list_dir, glob, memory_search]
---

Use subagents_run when tasks are independent and can fan out in parallel:

{"tasks": [
  {"prompt": "find all API endpoints", "tier": "light"},
  {"prompt": "design the migration plan", "tier": "heavy"}
]}

Advanced staged-flow tools are available only when explicitly allowed for a session: subagents_orchestrate runs dependency-aware parallel / sequential steps, and subagents_plan uses the heavy-tier planner model to draft such a flow.

Experimental consensus mode remains hidden from the default subagents_run schema unless agentruntime.consensus.enabled is explicitly set.

Tier resolution priority: task tier > agent YAML tier > config default.

The Console Agent Runtime page exposes Runs | Subagents tabs. Use Runs to filter execution history by status, time range, and prompt text, switch between list/tree/Gantt/Flow run views, pan and zoom an interactive Svelte Flow graph, jump back to the originating chat session, scan today/7d/plan cost totals, scrub timestamped run events with Replay, inspect each run's cost/token flow, and review file attention for frequently read or edited workspace paths. Use Subagents to inspect the active catalog, default/effective LLM tier, resolved provider/model, source file or command entry, tool policy, and recent run links. Workspace AGENT.md profiles can update their default tier, draft new subagents with an LLM-assisted builder, preview and approve LLM edits, and archive inactive workspace profiles from this detail view.

3-Tier Model Routing

Route workloads to different models for cost and quality optimization:

Tier	Purpose	Example
heavy	Planning, complex reasoning, architecture	claude-opus-4-6, gpt-5.4
standard	General chat, agent loops, tool calling	claude-sonnet-4-6, gpt-5.4
light	Summarization, classification, pulse, reflection	claude-haiku-4-5, gpt-4o-mini

# tars.config.yaml
llm:
  providers:
    default:
      kind: anthropic
      auth_mode: api-key
      api_key: ${ANTHROPIC_API_KEY}
  tiers:
    heavy:
      provider: default
      model: claude-opus-4-6
    standard:
      provider: default
      model: claude-sonnet-4-6
    light:
      provider: default
      model: claude-haiku-4-5
  default_tier: standard
  role_defaults:
    pulse_decider: light
    agentruntime_planner: heavy

Each system role (chat, pulse, reflection, compaction, agent runtime agents) maps to a tier. Background surfaces default to light, keeping costs low. If advanced staged subagent planning is explicitly enabled for a session, llm_role_agentruntime_planner is exercised by subagents_plan; TARS logs the resolved role, tier, provider, model, and source for chat and agent runtime LLM calls so tier selection is traceable in runtime logs. The Console Settings page includes a typed llm.tiers editor for adding, renaming, editing, and removing tier bindings without hand-editing JSON.

Background Surfaces

Two isolated surfaces run independently from user chat:

• Pulse — 1-minute watchdog scanning cron failures, stuck runs, disk pressure, Telegram delivery health, and reflection status. LLM classifier picks ignore / notify / autofix. Autofixes are whitelisted in config.
• Reflection — Nightly batch (default 02:00–05:00) running memory reflection (experience extraction) and stale empty-session pruning.

Both use the light tier by default and have no access to user-facing tools (enforced at compile time via RegistryScope).

Scheduling

Native cron with session binding:

• Cron expressions and one-shot @at schedules
• Session-bound jobs inherit the session's tool policy, work dirs, and prompt override
• Audit logs: artifacts/<session_id>/cronjob-log.jsonl
• Console Cron tab for per-session job management

Channels

Multi-channel I/O beyond the web console:

• Telegram — Bidirectional messaging with pairing-based access control
• Webhooks — Inbound HTTP triggers for external integrations
• Local — Direct API calls for scripts and automation

Extensibility

TARS favors on-demand extension over always-resident tool registrations. Domain-specific capabilities are shipped as skills (plus optional companion CLIs) from the Skill Hub rather than compiled into the TARS binary — this keeps the chat system prompt small no matter how many capabilities a user installs.

• Skill Hub — Public registry of skills, plugins, and MCP servers. Install with tars skill install <name>, tars plugin install <name>, tars mcp install <name>. The hub is the first place to look before writing a new capability, and the only place to publish one.
• Skills — Markdown instruction files (YAML frontmatter + body) with optional companion scripts. A skill's frontmatter can set recommended_tools: [bash], slash: /name, and aliases: [...]; users can invoke eligible skills directly from chat via /name autocomplete. Companion CLIs keep their interface out of the system prompt until the skill itself is picked. The Extensions console can draft, sandbox-test, and save local workspace/skills/<name>/ skills before you publish them to the hub. See daily-briefing in the hub for the canonical pattern.
• Plugins — Bundle skills + MCP servers with manifest metadata and runtime gating.
• MCP — Local stdio and remote HTTP/WebSocket servers with bearer or OAuth auth. Use for third-party integrations that cannot be expressed as a CLI the bash tool can call.
• Browser — Playwright-based automation for web interaction (shipped as a hub plugin).

When to build a hub skill vs. a core feature: if the capability is domain-specific (one site's logs, one vendor's API, one workflow), it belongs in tars-skills as a skill + CLI. Builtin tools inside this repo are reserved for universal surfaces (file ops, memory, agent runtime, channels) that every session uses.

Install

Homebrew:

brew tap devlikebear/tap
brew install devlikebear/tap/tars

Curl:

curl -fsSL https://raw.githubusercontent.com/devlikebear/tars/main/install.sh | sh

Quick Start

# Initialize workspace and config
tars init

# Set your provider credentials
export ANTHROPIC_API_KEY="your-key"
# Or: export OPENAI_API_KEY="your-key"
# Then edit ~/.tars/config/config.yaml under llm.providers / llm.tiers if needed

# Validate setup
tars doctor --fix

# Start the server
tars serve

# Open the web console
tars

Open http://127.0.0.1:43180/console and start chatting.

Console Pages

Page	Path	Purpose
Chat	/console	Interactive agent chat with tool calling, @ file/directory/subagent mentions, / skill commands, Files workspace shell, and advanced /config session policy overrides
Agent Runtime	/console/agentruntime	Inspect subagent run history with filters, list/tree/Gantt/Flow views, originating session links, cost summaries, replay scrubber, per-run cost/token flow, file attention, and subagent tier management
Memory	/console/memory	Edit stored knowledge assets with inline guidance, inspect fill/read metadata, and try semantic recall searches
System Prompt	/console/sysprompt	Edit USER.md, IDENTITY.md, AGENTS.md, TOOLS.md with starter templates, prompt impact metadata, preview, and a technical details toggle
Approvals	/console/approvals	Review risky cleanup plans before TARS applies them
Pulse	/console/pulse	Watchdog status and run-now trigger
Reflection	/console/reflection	Nightly batch status and run-now trigger
Extensions	/console/extensions	Skills, local Skill Creator drafts/tests, plugins, MCP servers
Config	/console/config	Workspace configuration with structured object/array editing and typed LLM tier editing

Requirements

• Go 1.25.6+ (for building from source)
• LLM provider credentials (Anthropic, OpenAI, Gemini, or Claude Code CLI)
• Optional: Gemini API key for semantic memory embeddings
• Optional: Node.js for Playwright browser automation

Build

make build-bins
bin/tars version

For development with hot-reload:

make dev-console    # Vite (5173) + Go API (43180), open http://127.0.0.1:43180/console

Documentation

• Getting Started
• Plugin and MCP Packaging Guide
• Contributing
• Changelog

Status

Pre-1.0.0 — Module path: github.com/devlikebear/tars