tarsk 0.6.88 → 0.6.89

package/README.md

@@ -1,20 +1,22 @@
 # Tarsk CLI
 
-[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.
+[Tarsk](https://tarsk.io) is an AI coding and knowledge 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](https://tarsk.io) app and exposes the API for repository management, agent execution, and project workflows.
+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. The same server powers the macOS desktop app (Electrobun).
 
 ## 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.
+- **Goals** — Run long-lived objectives with `/goal` across verified rounds and fresh context.
 - **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.
+- **Slack** — Bind channels to projects and drive Tarsk from Slack (Socket Mode).
+- **Browser and terminal** — Run project commands, open dev servers in an embedded browser (desktop), and use integrated terminals.
 
 ## Quick start
 
@@ -32,14 +34,18 @@ To always use the latest published version:
 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.
+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. Closing the window keeps the server running; quit from the menu bar tray.
 
 ## CLI options
 
-| Flag       | Description                                                                                                                                                              |
-| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| 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**.                                                                                              |
+| `--debug` | Enable verbose logging. Runs the server on port **462** instead of **641**. |
+| `--port <n>` | Server port in normal mode (sets `PORT`; default **641**). Ignored when `--debug` is set. |
+| `--open` | Open the browser even when `--server` is set. |
+| `--data-dir <path>` | Override the data directory (sets `TARSK_DATA_DIR`). |
+| `--assets-dir <path>` | Override companion server assets (`public/`, bundled skills, etc.; sets `TARSK_ASSETS_DIR`). |
 
 Examples:
 
@@ -47,41 +53,74 @@ Examples:
 npx tarsk --server          # headless server
 npx tarsk --debug           # troubleshoot with full logs
 npx tarsk --server --debug  # headless server with verbose logging
+npx tarsk --port 3000       # custom port (normal mode)
 ```
 
 ### Environment variables
 
-| Variable | Description                                                                                           |
-| -------- | ----------------------------------------------------------------------------------------------------- |
-| `PORT`   | Server port in normal mode (default: `641`). Ignored when `--debug` is set (debug always uses `462`). |
+| Variable | Description |
+| -------- | ----------- |
+| `PORT` | Server port in normal mode (default: `641`). Ignored when `--debug` is set (debug always uses `462`). |
+| `TARSK_APP_SUPPORT_DIR` | Root application support directory (logs, `port.json`, default layout). |
+| `TARSK_DATA_DIR` | Data directory (defaults to `<appSupport>/data`). Same effect as `--data-dir`. |
+| `TARSK_ASSETS_DIR` | Directory with bundled server assets. Same effect as `--assets-dir`. |
+| `MODE` | Set to `development` when running from the monorepo (`bun run web`); suppresses auto-open unless `--open` is passed. |
 
 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. |
+| 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. |
+
+Tarsk checks for `git` during onboarding on first launch and surfaces a warning with a download link if it is missing.
 
 ## Where data is stored
 
-All Tarsk data lives in your user data directory:
+All Tarsk data lives under your application support directory:
+
+| Platform | Default path |
+| -------- | ------------ |
+| macOS | `~/Library/Application Support/Tarsk/` |
+| Linux / Windows (CLI) | Same path under your home directory unless you override it (see below). |
 
-| Platform | Path                                   |
-| -------- | -------------------------------------- |
-| macOS    | `~/Library/Application Support/Tarsk/` |
-| Windows  | `%APPDATA%\Tarsk\`                     |
-| Linux    | `~/.config/Tarsk/`                     |
+The desktop app and CLI share these defaults. Set `TARSK_APP_SUPPORT_DIR` to move the whole tree (logs, `port.json`, and `data/`). Use `--data-dir` or `TARSK_DATA_DIR` to relocate only the `data/` folder. On Linux or Windows, set `TARSK_APP_SUPPORT_DIR` if you want a conventional path such as `~/.config/Tarsk`.
 
-Inside this directory:
+Inside the application support directory:
 
-- `tarsk.db` — SQLite database (projects, threads, conversations, settings)
-- `data/{threadId}/` — one directory per thread, containing the full git working copy for that thread
+- `data/tarsk.db` — SQLite database (projects, threads, conversations, settings)
+- `data/{repo-slug}/` — one directory per thread, each a full git working copy (for example `org-repo` from `https://github.com/org/repo`, with `-1`, `-2`, … when names collide)
+- `port.json` — active server port (written when the server starts)
 
 Each thread is a real, independent filesystem copy of your repository.
 
+## Remote access
+
+To use Tarsk from another device, sign in and enable **Mobile & Network Access** in **Settings → Remote Access**. Tarsk provisions a public address on tarsk.net; visitors must sign in as the same account. Restart Tarsk after changing this setting. See [Remote Access](https://tarsk.io/docs/settings/remote-machines/) in the product docs.
+
+## Developing from the monorepo
+
+From the repository root, see [README.md](../README.md) for full monorepo setup, build order, and `check:all`.
+
+Common workflows inside `cli/`:
+
+| Command | Purpose |
+| ------- | ------- |
+| `bun run web` | Run the server in development mode (same as root `bun run dev:cli`). |
+| `bun run dev` | Build frontend assets and launch the Electrobun desktop app in dev mode. |
+| `bun run dev:web` | Debug API on **462** plus Vite on **8100** (hot reload). |
+| `bun run build` | Production desktop build (codesigned when configured). |
+| `bun run build:unsigned` | Desktop build without codesign/notarize (CI and sandboxes). |
+| `bun run build:npm` | Server bundle only (published `npx tarsk` artifact). |
+| `bun run test` | CLI tests (`vp test run`, not bare `bun test`). |
+
+Implementation notes for contributors: [agents.md](agents.md) and [AGENTS.md](../AGENTS.md).
+
 ## Documentation
 
 - [tarsk.io/docs](https://tarsk.io/docs) — product documentation
+- [Installation](https://tarsk.io/docs/getting-started/installation/) — flags, data paths, and requirements
+- [README.md](../README.md) — monorepo layout and development