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.

Installation

Requirements

• Rust - Rust toolchain and Cargo
• Docker or Podman - Container runtime
• Git - Version control system
• One of the supported coding agents:
• Claude Code
• Codex
• Help us support more!

Install tsk

# 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:

/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 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.

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:

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 for the feat type and 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.

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 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:

tsk server start --workers 4

Now, in another terminal window, we can quickly queue up multiple tasks:

# 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 <taskid>

# 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:

# 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 <taskid> with the parent's ID)
tsk add -t feat -n add-tests -p "Add integration tests for the users API" --parent <taskid>

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:

# 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 <issue-number> | 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 <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 <branch> to start from a specific branch's HEAD)
• tsk add - Queue a task (supports --parent <taskid> for task chaining, --wait to block until completion, --branch <branch> to start from a specific branch's HEAD)
• tsk list - View task status and branches
• tsk wait <task-id>... - Block until one or more tasks complete
• tsk cancel <task-id>... - Cancel one or more running or queued tasks
• tsk clean - Clean up completed tasks
• tsk delete <task-id>... - Delete one or more tasks
• tsk retry <task-id>... - 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 <template> - Display the contents of a template
• tsk template edit <template> - Open a template in your editor for customization

Run tsk help or tsk help <command> for detailed options.

Configuring tsk

tsk has 3 levels of configuration in priority order: - Project level in the .tsk folder local to your project - User level in ~/.config/tsk - Built-in configurations

Each configuration directory can contain: - templates: A folder of task template markdown files which can be used via the -t/--type flag

Configuration File

tsk can be configured at two levels:

1. User-level: ~/.config/tsk/tsk.toml — global settings, defaults, and per-project overrides
2. Project-level: .tsk/tsk.toml in your project root — shared project defaults (checked into version control)

Both levels use the same shared config shape. The project-level config only contains shared settings (no container_engine, [server], or [project.<name>] sections).

User-level config (~/.config/tsk/tsk.toml):

```toml

Container engine (top-level setting, user-only)

container_engine = "docker" # "docker" (default) or "podman"

Server daemon configuration (user-only)

[server] auto_clean_enabled = true # Automatically clean old tasks (default: true) auto_clean_age_days = 7.0 # Minimum age in days before cleanup (default: 7.0)

Default settings for all projects (showing built-in defaults)

[defaults] agent = "claude" # AI agent: "claude" or "codex" stack = "default" # Tech stack (auto-detected from project files) memory_gb = 12.0 # Container memory limit in GB cpu = 8 # Number of CPUs dind = false # Enable Docker-in-Docker support privileged = false # Run containers in privileged mode (disables security restrictions) sudo = false # Enable passwordless sudo inside containers devices = [] # Device paths to expose (e.g., ["/dev/video0"]) git_town = false # Enable git-town parent branch tracking

Project-specific overrides (matches directory name)

[project.my-go-service] stack = "go" memory_gb = 24.0 cpu = 16 setup = ''' USER root RUN apt-get update && apt-get install -y libssl-dev pkg-config USER agent ''' host_ports = [5432, 6379] # Forward host ports to containers volumes = [ # Bind mount: share host directories with containers (supports ~ expansion) { host = "~/.cache/go-mod", container = "/go/pkg/mod" }, # Named volume: container-managed persistent storage (prefixed with tsk-) { name = "go-build-cache", container = "/home/agent/.cache/go-build" }, # Read-only mount: provide artifacts without modification risk { host = "~/debug-logs", container = "/debug-logs", readonly = true } ] env =