tars

README

TARS

TARS is a local-first automation runtime written in Go.

It combines a terminal client, a local HTTP runtime, agent tools, sessions, scheduling, and optional browser automation in a single repository.

Status

• Pre-1.0.0
• Primary module path: github.com/devlikebear/tars
• Version source: VERSION.txt
• Release notes: CHANGELOG.md

Core Capabilities

• Terminal client with a Bubble Tea TUI
• Local HTTP API via tars serve
• Project manager workflow with a project board, activity feed, dispatch API, and GitHub Flow status dashboard
• Session lifecycle and transcript storage
• Agent loop with built-in file, process, scheduling, memory, and ops tools
• Runtime extension loading for skills, plugins, and MCP servers
• Playwright-based browser automation
• Optional macOS assistant workflow

Requirements

• Go 1.25.6 or newer
• Provider credentials for the models you want to use
• Optional: Node.js for Playwright browser installation

Install

Homebrew tap:

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

Curl installer:

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

The installer downloads the latest published GitHub Release by default.

Install to a custom path or pin a version:

curl -fsSL https://raw.githubusercontent.com/devlikebear/tars/main/install.sh | INSTALL_DIR="$HOME/.local/bin" VERSION=0.2.0 sh

Quick Start

1. Initialize a starter workspace and config:

tars init

1. Export a BYOK provider key for the starter config:

export OPENAI_API_KEY="your-api-key"

1. Check or repair the local starter setup:

tars doctor
tars doctor --fix

--fix only creates missing local files and directories. Provider credentials still need to be configured separately.

1. Install and start the macOS background service:

tars service install
tars service start
tars service status

1. Start the local server manually if you do not want a background service:

tars serve --config ./workspace/config/tars.config.yaml

Open a project dashboard in the browser:

open http://127.0.0.1:43180/ui/projects/<project-id>

The dashboard renders the current board, recent activity, and GitHub Flow task metadata. Live updates stream from:

curl -N http://127.0.0.1:43180/ui/projects/<project-id>/stream

1. Start the client:

tars

Kick off a project from chat:

todo 앱 만드는 프로젝트 시작해줘

The bundled project-start skill will collect a few brief answers, finalize the project, seed the board, and start background autopilot execution.

1. Run basic checks:

make api-status
make api-sessions
make smoke-auth

Project Manager API

TARS now ships a bundled project-swarm plugin under plugins/project-swarm. Its skills are mirrored into the workspace runtime and can be invoked explicitly with /project-start or selected automatically from natural-language kickoff messages in chat and Telegram.

For direct API control, the project manager routes remain available:

Create a project:

curl -s http://127.0.0.1:43180/v1/projects \
  -H 'Content-Type: application/json' \
  -d '{"name":"Project PM Demo","type":"operations","objective":"Ship the MVP"}'

Seed or update the board:

curl -s http://127.0.0.1:43180/v1/projects/<project-id>/board \
  -X PATCH \
  -H 'Content-Type: application/json' \
  -d '{
    "tasks":[
      {
        "id":"task-1",
        "title":"Implement feature",
        "status":"todo",
        "assignee":"dev-1",
        "role":"developer",
        "review_required":true,
        "test_command":"go test ./internal/project",
        "build_command":"go test ./internal/tarsserver"
      }
    ]
  }'

Dispatch developer work and then reviewer work:

curl -s http://127.0.0.1:43180/v1/projects/<project-id>/dispatch \
  -X POST \
  -H 'Content-Type: application/json' \
  -d '{"stage":"todo"}'

curl -s http://127.0.0.1:43180/v1/projects/<project-id>/dispatch \
  -X POST \
  -H 'Content-Type: application/json' \
  -d '{"stage":"review"}'

Tasks that require review will only move to done after the reviewer stage approves them. Developer runs must also report passing test/build results plus issue/branch/PR metadata before the task can advance.

An end-to-end curl example is available in examples/project/README.md.

Build

Build the binary with version metadata from VERSION.txt:

make build-bins
bin/tars version

Build a macOS release archive with the same version metadata used by GitHub Releases:

make release-asset RELEASE_GOOS=darwin RELEASE_GOARCH=arm64

Browser Automation

Playwright runtime is the primary browser automation path.

• Install browser dependencies with make browser-install
• Configure browser-related settings in workspace/config/tars.config.yaml
• Use the runtime APIs and TUI commands for browser status, profiles, login checks, and runs

The Chrome relay extension in web/relay-extension/README.md is still available as an experimental legacy workflow for local debugging.

Security

• Default API auth mode is token-based and role-aware
• High-risk tools are restricted by default on non-admin routes
• Run make security-scan before publishing or tagging a release

Repository Layout

• cmd/tars: CLI entrypoint for client, server, and assistant commands
• internal/*: runtime packages
• config/: example and standalone configuration
• workspace/: local runtime state, ignored by Git
• web/relay-extension/: optional Chrome extension for the legacy relay flow

Contributing

See CONTRIBUTING.md for development workflow, release rules, and PR requirements.

Getting Started

See GETTING_STARTED.md for a short setup and operations guide.