# tsk-tsk: keeping your agents out of trouble Delegate development `tsk` tasks to YOLO mode AI agents running in sandbox containers. `tsk` auto-detects your toolchain and builds container images for you, so most projects require very little setup. Agents work asynchronously and in parallel so you can review their work on your own schedule, respecting your time and attention. 1. **Assign tasks** using templates that automate prompt boilerplate 2. **`tsk` copies your repo** and builds containers with your toolchain automatically 3. **Agents work in YOLO mode** in parallel filesystem and network isolated containers 4. **`tsk` fetches branches** back to your repo for review 5. **Review and merge** on your own schedule Each agent gets what it needs and nothing more: - Agent configuration (e.g. `~/.claude` or `~/.codex`) - A copy of your repo excluding gitignored files (no accidental API key sharing) - An isolated filesystem (no accidental `rm -rf .git`) - A configurable domain allowlist (Agents can't share your code on MoltBook) Each agent runs in an isolated network where all traffic routes through a proxy sidecar, enforcing the domain allowlist. Beyond network restrictions, agents have full control within their container. Supports Claude Code and Codex coding agents. Docker and Podman container runtimes. ![tsk demo](./docs/images/tsk-demo.gif) ## Installation ### Requirements - [Rust](https://rustup.rs/) - Rust toolchain and Cargo - [Docker](https://docs.docker.com/get-docker/) or [Podman](https://podman.io/) - Container runtime - [Git](https://git-scm.com/downloads) - Version control system - One of the supported coding agents: - [Claude Code](https://docs.anthropic.com/en/docs/claude-code) - [Codex](https://openai.com/codex/) - Help us support more! ### Install `tsk` ```bash # Install using cargo cargo install tsk-ai # Or build from source! gh repo clone dtormoen/tsk-tsk cd tsk-tsk cargo install --path . ``` **Claude Code users:** Install `tsk` skills to teach Claude how to use `tsk` commands directly in your conversations and help you configure your projects for use with `tsk`: ```bash /plugin marketplace add dtormoen/tsk-tsk /plugin install tsk-help@dtormoen/tsk-tsk /plugin install tsk-config@dtormoen/tsk-tsk /plugin install tsk-add@dtormoen/tsk-tsk ``` See [Claude Code Skills Marketplace](#claude-code-skills-marketplace) for more details. ## Quick Start Guide `tsk` can be used in multiple ways. Here are some of the main workflows to get started. Try testing these in the `tsk` repository! ### Interactive Sandboxes Start up sandbox with an interactive shell so you can work interactively with a coding agent. This is similar to a git worktrees workflow, but provides stronger isolation. `claude` is the default coding agent, but you can also specify `--agent codex` to use `codex`. ```bash tsk shell ``` The `tsk shell` command will: - Make a copy of your repo - Create a new git branch for you to work on - Start a proxy to limit internet access - Build and start a container with your stack (go, python, rust, etc.) and agent (default: claude) installed - Drop you into an interactive shell After you exit the interactive shell (ctrl-d or `exit`), `tsk` will save any work you've done as a new branch in your original repo. This workflow is really powerful when used with terminal multiplexers like `tmux` or `zellij`. It allows you to start multiple agents that are working on completely isolated copies of your repository with no opportunity to interfere with each other or access resources outside of the container. ### One-off Fully Autonomous Agent Sandboxes `tsk` has flags that help you avoid repetitive instructions like "make sure unit tests pass", "update documentation", or "write a descriptive commit message". Consider this command which immediately kicks off an autonomous agent in a sandbox to implement a new feature: ```bash tsk run --type feat --name greeting --prompt "Add a greeting to all tsk commands." ``` Some important parts of the command: - `--type` specifies the type of task the agent is working on. Using `tsk` built-in tasks or writing your own can save a lot of boilerplate. Check out [feat.md](./templates/feat.md) for the `feat` type and [templates](./templates) for all task types. - `--name` will be used in the final git branch to help you remember what task the branch contains. - `--prompt` is used to fill in the `{{PROMPT}}` placeholder in [feat.md](./templates/feat.md). Similar to `tsk shell`, the agent will run in a sandbox so it will not interfere with any ongoing work and will create a new branch in your repository in the background once it is done working. Add `--branch main` to start from a specific branch's committed state instead of your current working tree. This is useful when you want to launch a task from a different branch without switching to it. After you try this command out, try out these next steps: - Add the `--edit` flag to edit the full prompt that is sent to the agent. - Add a custom task type. Use `tsk template list` to see existing task templates and where you can add your own custom tasks. - See the [custom templates used by `tsk`](./.tsk/templates) for inspiration. ### Queuing Tasks for Parallel Execution The `tsk` server allows you to have a single process that manages parallel task execution so you can easily background agents working. First, we start the server set up to handle up to 4 tasks in parallel: ```bash tsk server start --workers 4 ``` Now, in another terminal window, we can quickly queue up multiple tasks: ```bash # Add a task. Notice the similarity to the `tsk run` command tsk add --type doc --name tsk-architecture --prompt "Tell me how tsk works" # Look at the task queue. Your task `tsk-architecture` should be present in the list tsk list # Add another task. Notice the short flag names tsk add -t feat -n greeting -p "Add a silly robot greeting to every tsk command" # Now there should be two running tasks tsk list # Wait for a specific task to finish (blocks until complete) tsk wait # Or look at all the branches after tasks complete git branch --format="%(refname:short) - %(subject) (%(committerdate:relative))" ``` After you try this command out, try these next steps: - Use `tsk add --wait` to queue a task and block until it completes (useful in scripts and CI) - Add tasks from multiple repositories in parallel - Start up multiple agents at once - Adding `--agent codex` will use `codex` to perform the task - Adding `--agent codex,claude` will have `codex` and `claude` do the task in parallel with the same environment and instructions so you can compare agent performance - Adding `--agent claude,claude` will have `claude` do the task twice. This can be useful for exploratory changes to get ideas quickly ### Task Chaining Chain tasks together with `--parent` so a child task starts from where its parent left off: ```bash # First task: set up the foundation tsk add -t feat -n add-api -p "Add a REST API endpoint for users" # Check the task list to get the task ID tsk list # Second task: chain it to the first (replace with the parent's ID) tsk add -t feat -n add-tests -p "Add integration tests for the users API" --parent ``` Child tasks wait for their parent to complete, then start from the parent's final commit. `tsk list` shows these tasks as `WAITING`. If a parent fails, its children are automatically marked as `FAILED`; if a parent is cancelled, its children are marked as `CANCELLED`. Chains of any length (A → B → C) are supported. ### Create a Simple Task Template Let's create a very basic way to automate working on GitHub issues: ```bash # First create the tsk template configuration directory mkdir -p ~/.config/tsk/templates # Create a very simple template. Notice the use of the "{{PROMPT}}" placeholder cat > ~/.config/tsk/templates/issue-bot.md << 'EOF' Solve the GitHub issue below. Make sure it is tested and write a descriptive commit message describing the changes after you are done. {{PROMPT}} EOF # Make sure tsk sees the new `issue-bot` task template tsk template list # Pipe in some input to start the task # Piped input automatically replaces the {{PROMPT}} placeholder gh issue view | tsk add -t issue-bot -n fix-my-issue ``` Now it's easy to solve GitHub issues with a simple task template. Try this with code reviews as well to easily respond to feedback. ## Commands ### Task Commands Create, manage, and monitor tasks assigned to AI agents. - `tsk run` - Execute a task immediately (supports `--branch ` to start from a specific branch's HEAD; Ctrl+C marks task as CANCELLED) - `tsk shell` - Start a sandbox container with an interactive shell (supports `--branch ` to start from a specific branch's HEAD) - `tsk add` - Queue a task (supports `--parent ` for task chaining, `--wait` to block until completion, `--branch ` to start from a specific branch's HEAD) - `tsk list` - View task status and branches - `tsk wait ...` - Block until one or more tasks complete (exits non-zero if any task failed, was cancelled, or is blocked by a warmup error) - `tsk cancel ...` - Cancel one or more running or queued tasks - `tsk clean` - Clean up completed tasks - `tsk delete ...` - Delete one or more tasks - `tsk retry ...` - Retry one or more tasks ### Server Commands Manage the `tsk` server daemon for parallel task execution. The server automatically cleans up completed, failed, and cancelled tasks older than 7 days. - `tsk server start` - Start the `tsk` server daemon - `tsk server stop` - Stop the running `tsk` server Graceful shutdown (via `q`, Ctrl+C, or `tsk server stop`) marks any in-progress tasks as CANCELLED. When running in an interactive terminal, `tsk server start` shows a TUI dashboard with a split-pane view: task list on the left, log viewer on the right. In the task list, active tasks (Running, Queued, Waiting) appear above completed or failed tasks. The log viewer starts at the bottom of the selected task's output and auto-follows new content. Scrolling up pauses follow mode; scrolling back to the bottom resumes it. When stdout is piped or non-interactive (e.g. `tsk server start | cat`), plain text output is used instead. **TUI Controls:** - `Left` / `h`: Focus the task list panel - `Right` / `l`: Focus the log viewer panel - `Up` / `k`, `Down` / `j`: Navigate tasks or scroll logs (depends on focused panel) - `Page Up` / `Page Down`: Jump scroll in log viewer - Click: Select a task or focus a panel - Mouse scroll: scroll tasks or logs - Scrollbar click/drag: Jump or scrub through the task list - `Shift+click` / `Shift+drag`: Select text (bypasses mouse capture for clipboard use) - `c`: Cancel the selected task (when task panel is focused, only RUNNING/QUEUED tasks) - `d`: Delete the selected task (when task panel is focused, only terminal-state tasks) - `q`: Quit the server (graceful shutdown) ### Configuration Commands Build container images and manage task templates. - `tsk docker build` - Build required container images - `tsk template list` - View available task type templates and where they are installed - `tsk template show