tars-agent

TARS — a disciplined, multi-session coding agent loop

Why it exists

Named for TARS - the robot from Interstellar - whose worth lies not in cleverness but in discipline: it does what it said, reports honestly what it did, and asks before it touches anything. This tool tries to earn that name.

Install

pip install -e ".[dev]"

Or install the published package:

pipx install tars-agent
pip install tars-agent

Requires Python >=3.10.

This project has no runtime dependencies.

Quick Start

Get TARS running in 60 seconds:

pipx install tars-agent
# or: pip install tars-agent
tars setup
tars

Inside the REPL, new sessions start in Chat mode. Tab cycles Chat → Plan → Agent; /mode chat|plan|agent switches explicitly. Bare prompts follow the selected mode:

◐ chat › Explain how tars/memory scores candidates
◐ plan › Add dark mode to src/App.tsx and verify with tests
◐ agent › Fix the failing test in tests/test_login.py

Commands:

Plan mode never mutates files. Agent mode is the full disciplined workflow and keeps ACT previews behind confirmation. For command history, multiline input, and slash completion, install the optional composer:

pipx inject tars-agent prompt-toolkit

One-shot (no REPL):

tars run "Fix bug in app.py --yes"
tars route "Add a new CLI flag"

Configure the cheapest model for simple tasks:

export TARS_TIER0_MODEL=openrouter:minimax/minimax-m3:free
# tier 0 (scaffold/create-artifact) uses this; tiers 1-2 stay on the flagship

Browser testing (optional):

pip install "tars-agent[browser]"
tars run "Check https://example.com loads and has a login button" --web-url https://example.com --web-expect "login"

How to run it

tars

Run TARS's disciplined agent loop.

tars
python -m tars.loop

Flags: --version, --yes, --root, --model, --web-url, --web-steps, --web-expect

_{declared in pyproject.toml}

tars-browser

Efficient accessibility-tree-first web testing.

tars-browser
python -m tars.browser

_{declared in pyproject.toml}

tars-memory

Read a session transcript and propose the memory entries it earned: domain-tagged, scored, and quoted from the turn they came from. Also reads back what earlier sessions kept.

tars-memory
python -m tars.memory

Flags: --write, --session, --max, --now, --domain, --kind, --limit, --root, --json, --no-color

_{declared in pyproject.toml}

tars-readme

Write a README from what a repo actually contains: usage examples lifted from its own docstrings and tests, the commands it declares, and the checks it can run.

tars-readme
python -m tars.readme

Flags: -o/--output, --force, --check, --json, --include-unverified, --notes, --no-tests, --max-examples, --no-color

_{declared in pyproject.toml}

tars-verify

Detect a repo's test runner, linter, type-checker and formatter, then run them uniformly.

tars-verify
python -m tars.verification

Flags: --only, --include, --list, --json, --fail-fast, --timeout, --output-lines, --max-output-chars, --allow-no-checks, --quiet/-q, --no-color

_{declared in pyproject.toml}

python -m tars

Efficient accessibility-tree-first web testing.

python -m tars

_{declared in tars/__main__.py}

Examples

Every snippet below was taken from the file named under it, and checked against the current source.

from tars.act import Edit, Hunk, LocalExecutor

executor = LocalExecutor(".")
result = executor.apply(Edit.replace("a.py", Hunk("x = 1", "x = 2")))
result.ok, result.diff, result.touched

_{tars/act/__init__.py:5}

from tars.act import Command, LocalExecutor

LocalExecutor(".").run(Command(["pytest", "-q"])).reason

_{tars/act/__init__.py:24}

from tars.act import Edit, Hunk, LocalExecutor

preview = LocalExecutor(".", dry_run=True)
preview.apply(Edit.replace("a.py", Hunk("x = 1", "x = 2"))).diff

_{tars/act/__init__.py:40}

from tars.act import get_executor, known_executors

get_executor("local")
known_executors()

_{tars/act/__init__.py:48}

from tars.memory import reflect_on

report = reflect_on("run/session.jsonl")
report.summary_line()
report.to_commit    # high-confidence, decision-shaped, domain-tagged
report.to_review    # what a human should see before anything believes it
report.dropped      # considered, scored too low, kept so you can see it

_{tars/memory/__init__.py:7}

from tars.memory import reflect_on

reflect_on("run/session.jsonl").nothing_worth_remembering

_{tars/memory/__init__.py:22}

How it's structured

• tars/__init__.py — TARS — a disciplined, multi-session coding agent loop. (python -m tars)
  • tars/_cli_helpers.py — Shared CLI helpers: color and tty detection.
  • tars/act/__init__.py — TARS ACT — PHASE 4, isolated: the phase that actually touches the repo.
    • tars/act/base.py — The one interface every executor implements.
    • tars/act/local.py — The built-in executor: this machine, this repo, stdlib only.
    • tars/act/registry.py — Which executor does ACT's work, chosen by name rather than by import.
    • tars/act/types.py — What ACT was asked to do, and what came of it.
  • tars/browser/__init__.py — Efficient, accessibility-tree-first browser testing. (python -m tars.browser)
    • tars/browser/cli.py — tars-browser: scriptable accessibility-tree web tests.
  • tars/loop/__init__.py — TARS loop orchestrator — the seven phases, driven. (python -m tars.loop)
    • tars/loop/_io.py — Small output helpers for the REPL.
    • tars/loop/cli.py — tars — persistent REPL and one-shot loop commands.
    • tars/loop/engine.py — The seven-phase loop, composed from TARS's tested phase modules.
    • tars/loop/modes.py — Chat and read-only Plan interactions, separate from the Agent engine.
    • tars/loop/repl.py — The persistent slash-command interface over one live :class:Session.
    • tars/loop/session.py — What persists between commands.
    • tars/loop/session_store.py — Durable event log for REPL sessions.
    • tars/loop/tools.py — Model-facing ACT tools.
    • tars/loop/tui.py — Optional prompt-toolkit composer for the inline TARS workspace.
    • tars/loop/types.py — The loop's own vocabulary.
  • tars/memory/__init__.py — TARS memory writer — PHASE 6 (REFLECT), isolated. (python -m tars.memory)
    • tars/memory/cli.py — tars-memory — the REFLECT phase as a command.
    • tars/memory/domains.py — Which partition does a fact belong to, and what said so.
    • tars/memory/propose.py — The REFLECT pass: read a transcript, propose what is worth remembering.
• …and 34 more modules

Tests live in tests/.

Verifying it

ruff check .
ruff format --check .
mypy tars tests
pytest

_{detected from this repo: format, lint, test, typecheck}

_{Generated by tars-readme from the source of this repository: 6 examples extracted from the paths above. Sections with nothing to source were left out.}