l̶e̶v̶e̶l̶ ̶1̶ ̶a̶u̶t̶o̶n̶o̶m̶y̶ ̶|̶ ̶c̶o̶d̶e̶ ̶s̶n̶i̶p̶p̶e̶t̶
 ▀█▀ ▄▀▄ █▀▄ ▄▀▀̶            l̶e̶v̶e̶l̶ ̶2̶ ̶a̶u̶t̶o̶n̶o̶m̶y̶ ̶|̶ ̶g̶e̶n̶e̶r̶a̶t̶e̶ ̶f̶e̶a̶t̶u̶r̶e̶
  █  █▀█ █▀▄ ▄██   Complete level 3 autonomy | Idea -> PR

Automated Claude CLI orchestrator for running implementation tasks with validation and verification.

Overview

TARS automates the full lifecycle from requirement to implementation:

Requirement → Spec → Tasks → Execute → Validate → Verify → Commit

| Stage | Script | Entry File | Description | |-------|--------|------------|-------------| | Spec | npm run pre | src/spec.mjs | Transforms requirements into SPEC.md + CONTEXT.md | | Plan | npm run setup | src/plan.mjs | Decomposes SPEC.md into dependency-ordered task files | | Execute | npm run build | src/run.mjs | Runs tasks through validation and verification pipeline | | Auto | npm start | src/start.mjs | State-aware orchestrator that runs chain as needed |

Installation

npm install -g tars-bot

Quick Start

# 1. Generate spec from a requirement
tars pre "Add user authentication with JWT"

# 2. Generate task files from the spec
tars setup

# 3. Execute all tasks
tars build

Or let TARS choose the required chain automatically:

tars start

Or use interactive spec mode:

tars pre
# Select from menu: type requirement or choose a file

End-to-End Lifecycle

+------------------+     +-----------------+     +-----------------------+
| Requirement text | --> | npm run pre     | --> | SPEC.md + CONTEXT.md  |
+------------------+     +-----------------+     +-----------------------+
                                                          |
                                                          v
                                               +-------------------------+
                                               | npm run setup           |
                                               | writes tasks/*.md       |
                                               +-------------------------+
                                                          |
                                                          v
                                               +-------------------------+
                                               | npm run build           |
                                               | execute/verify/commit   |
                                               +-------------------------+

npm start Chain Selection (src/start.mjs)

+------------------+
| npm start        |
| src/start.mjs    |
+------------------+
         |
         v
+---------------------------+
| tasks/*.md already exist? |
+------------+--------------+
             | yes
             v
      +----------------------+
      | run chain: [build]   |
      +----------------------+
             |
             no
             v
+----------------------------+
| SPEC.md plan-compatible?   |
+------------+---------------+
             | yes                         no
             v                             v
   +------------------------+    +-----------------------------+
   | run chain: [setup,     |    | run chain: [pre, setup,    |
   |            build]       |    |            build]           |
   +------------------------+    +-----------------------------+

Task Execution and Fix Loop (src/run.mjs)

            (optional with --plan or task override)
                         +------+
                         | Plan |
                         +--+---+
                            |
                            v
+---------+   +----------+   +------------+   +--------+   +--------+
| Execute |-> | Validate |-> | Regression |-> | Verify |-> | Commit |
+----+----+   +-----+----+   +------+-----+   +---+----+   +--------+
     |              |               |             |
     +--------------+---------------+-------------+
                    any failure in phase
                              |
                              v
                      +-------------------+
                      | Fix + retry phase |
                      | (bounded attempts)|
                      +-------------------+

Key settings in run.mjs:

const CONFIG = {
  maxFixAttempts: 3,           // Fix attempts before failing
  adversarialReview: true,     // Fresh session for verification
  planningEnabled: false,      // Enable via --plan flag
  phaseLimits: {
    plan:       { maxTurns: 15 },  // Planning needs exploration room
    execute:    { maxTurns: 30 },  // Implementation needs room
    verify:     { maxTurns: 8 },   // Verification should be focused
    fix:        { maxTurns: 15 },  // Fixes need moderate room
    commit:     { maxTurns: 3 },   // Commit is a simple action
    regression: { maxTurns: 15 },  // Test fix loop needs room
  },
};

Turn Limits

Each phase has a maxTurns limit that bounds how many tool calls Claude can make. This prevents over-elaboration and keeps phases focused:

• plan (15): Needs room to explore codebase and produce structured plan
• execute (30): Needs room for reading files, writing code, running commands
• verify (8): Should quickly check acceptance criteria, not re-implement
• fix (15): Moderate room to diagnose and fix issues
• commit (3): Just stage files and create a commit
• regression (15): Test fix loops need moderate room

Turn limits are passed to Claude CLI via --max-turns. When a phase hits its limit, Claude exits cleanly with whatever work was completed. Automated phases (validate, regression) don't have turn limits — they run shell commands directly.

The plan phase can dynamically adjust execute turns based on estimated complexity (see Planning Phase).

Documentation

| Guide | Description | |-------|-------------| | Spec Generator | Transform requirements into SPEC.md | | Plan Generator | Decompose specs into ordered tasks | | Task Runner | Execute, validate, verify, commit pipeline | | Parallel Execution | Run independent tasks concurrently | | Worktree Isolation | Git safety, interrupts & resume | | Self-Improvement | Runtime tuning harness | | Dashboard | Real-time TUI monitoring | | Logging | Structured logging & analytics | | Troubleshooting | Common issues & solutions | | Contributing | Adding tasks, JSDoc guidelines |

License

This project is dual-licensed:

| Use Case | License Required | |----------|--------------------| | Personal project | Free — PolyForm NC | | Learning / research | Free — PolyForm NC | | Open source (non-commercial) | Free — PolyForm NC | | Internal business tool | Commercial License | | Sold as part of a product | Commercial License | | Offered as a hosted service | Commercial License |

Attribution Required (All Users)

Whether you're using TARS for free or under a commercial license, the following is required:

• Acknowledgement: A visible credit ("Built with TARS") in your docs, README, about page, or website
• Console output: Your software must print a TARS attribution message on startup

→ Contact for commercial licensing