Tarsk CLI

Tarsk is an AI coding workspace for working with Git repositories in isolated threads. Each thread gets its own working copy, so you can explore ideas, run agents, review changes, and manage project work without disturbing your main branch.

The CLI starts a local Bun-powered server that serves the Tarsk app and exposes the API for repository management, agent execution, and project workflows.

Features

• Projects — Connect an existing Git repository, open a local folder, or scaffold a new app from a template.
• Threads — Create multiple isolated working copies per project for parallel experiments.
• AI agents — Chat with agents that can read and modify code inside a thread, with diff review before accepting changes.
• Tasks — Plan work in the Tasks view and jump into threads from tasks.
• Providers and models — Configure AI providers, models, and per-project model aliases.
• MCP servers — Attach Model Context Protocol servers for extended agent tooling.
• Rules, skills, and slash commands — Customize agent behavior with project rules, bundled skills, and reusable commands.
• Git workflows — Inspect status, review diffs, create commits, and open pull requests from the UI.
• Browser and terminal — Run project commands, open dev servers in an embedded browser, and use integrated terminals.

Quick start

No installation required:

npx tarsk

Tarsk starts on http://localhost:641 and opens your browser automatically. The server runs in the foreground — press Ctrl+C to stop it.

To always use the latest published version:

npx tarsk@latest

You can also download the macOS desktop app from tarsk.io. The desktop app bundles its own runtime and does not require Node.js.

CLI options

| Flag | Description | | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | --server | Start the API server only. Do not open a browser tab. Useful for headless operation, remote access, or when another client (desktop app, mobile) connects to the server. | | --debug | Enable verbose logging. Runs the server on port 462 instead of 641 and writes logs to ~/Library/Application Support/Tarsk/debug-logs.txt (macOS). |

Examples:

npx tarsk --server          # headless server
npx tarsk --debug           # troubleshoot with full logs
npx tarsk --server --debug  # headless server with verbose logging

Environment variables

| Variable | Description | | -------- | ----------------------------------------------------------------------------------------------------- | | PORT | Server port in normal mode (default: 641). Ignored when --debug is set (debug always uses 462). |

If the default port is already in use, Tarsk tries the next available port and prints the URL it bound to.

System requirements

| Requirement | Notes | | -------------------------- | ---------------------------------------------------------------------------- | | git | Required. Tarsk uses git to clone repositories and manage branches. | | Node.js 18+ or Bun | Required for npx tarsk. | | gh CLI (optional) | Needed for creating GitHub repositories and pull requests from within Tarsk. |

Where data is stored

All Tarsk data lives in your user data directory:

| Platform | Path | | -------- | -------------------------------------- | | macOS | ~/Library/Application Support/Tarsk/ | | Windows | %APPDATA%\Tarsk\ | | Linux | ~/.config/Tarsk/ |

Inside this directory:

• tarsk.db — SQLite database (projects, threads, conversations, settings)
• data/{threadId}/ — one directory per thread, containing the full git working copy for that thread

Each thread is a real, independent filesystem copy of your repository.

Documentation

• tarsk.io/docs — product documentation