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
• 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"}
]}

Use subagents_orchestrate when later tasks depend on earlier subagent results. It executes staged parallel and sequential steps and supports placeholders such as {{task.backend.summary}}.

Use subagents_plan before subagents_orchestrate when the main agent needs the heavy-tier planner model to decide which tasks should run in parallel versus sequence. The planner returns a validated staged flow that can be executed directly.

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

The Console Agent Runtime page exposes Runs | Subagents tabs. 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. llm_role_agentruntime_planner is now exercised by subagents_plan, and 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. 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, and Files workspace shell
Memory	/console/memory	Edit durable memory assets and test semantic search
System Prompt	/console/sysprompt	Edit USER.md, IDENTITY.md, AGENTS.md, TOOLS.md with starter templates for empty prompt files
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, 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