tarsk 0.5.50 → 0.5.51

package/README.md

@@ -1,5 +1,87 @@
-# Tarsk
+# Tarsk CLI
 
-Run `npx tarsk` to start the Tarsk App.
+[Tarsk](https://tarsk.io) 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.
 
-Use `npx tarsk --server` to start the server without opening a browser tab.
+The CLI starts a local Bun-powered server that serves the [Tarsk](https://tarsk.io) 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.
+- **Project todos** — Plan work on a kanban-style board 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:
+
+```bash
+npx tarsk
+```
+
+[Tarsk](https://tarsk.io) 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:
+
+```bash
+npx tarsk@latest
+```
+
+You can also download the macOS desktop app from [tarsk.io](https://tarsk.io/#download). 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:
+
+```bash
+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](https://tarsk.io/docs) — product documentation