A Rust CLI tool that lets you delegate development tasks to AI agents running in sandboxed Docker environments. Get back git branches for human review.
Currently Claude Code and Codex coding agents are supported.
TSK enables a "lead engineer + AI team" workflow:
- Assign tasks to AI agents with natural language descriptions and task type templates to automate prompt boilerplate
- Agents work autonomously in parallel isolated Docker containers
- Get git branches back with their changes for review
- Review and merge using your normal git workflow
Think of it as having a team of engineers who work independently and submit pull requests for review.
- Rust - Rust toolchain and Cargo
- Docker - Container runtime
- Git - Version control system
- One of the supported coding agents:
- Claude Code
- Codex
- Help us support more!
# Install using cargo
cargo install tsk-ai
# Or build from source!
gh repo clone dtormoen/tsk
cd tsk
cargo install .tsk run- Execute a task immediatelytsk shell- Start a sandbox container with an interactive shelltsk add- Queue a tasktsk list- View task status and branchestsk clean- Clean up completed taskstsk delete <task-id>...- Delete one or more taskstsk retry <task-id>...- Retry one or more tasks
tsk server start- Start the TSK server daemontsk server stop- Stop the running TSK server
tsk docker build- Build required docker imagestsk proxy stop- Stop the TSK proxy containertsk template list- View available task type templates and where they are installed
Run tsk help or tsk help <command> for detailed options.
TSK can be used in multiple ways. Here are some of the main workflows to get started. Try testing these in the TSK repository!
Start up sandbox with an interactive shell so you can work interactively with a coding agent. claude is the default, but you can also specify --agent codex to use codex.
tsk shellThe 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 docker 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.
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 --description "Add a greeting to all TSK commands."Some important parts of the command:
--typespecifies 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 thefeattype and templates for all task types.--namewill be used in the final git branch to help you remember what task the branch contains.--descriptionis used to fill in the{{description}}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.
After you try this command out, try out these next steps:
- Add the
--editflag to edit the full prompt that is sent to the agent. - Add a custom task type. Use
tsk template listto see existing task templates and where you can add your own custom tasks.- See the custom templates used by TSK for inspiration.
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 4Now, 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 --description "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 -d "Add a silly robot greeting to every TSK command"
# Now there should be two running tasks
tsk list
# Wait for the tasks to finish. After they complete, look at the two new branches
git branch --format="%(refname:short) - %(subject) (%(committerdate:relative))"After you try this command out, try these next steps:
- Add tasks from multiple repositories in parallel
- Start up multiple agents at once
- Adding
--agent codexwill usecodexto perform the task - Adding
--agent codex,claudewill havecodexandclaudedo the task in parallel with the same environment and instructions so you can compare agent performance - Adding
--agent claude,claudewill haveclaudedo the task twice. This can be useful for exploratory changes to get ideas quickly
- Adding
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 "{{DESCRIPTION}}" 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.
{{DESCRIPTION}}
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 {{DESCRIPTION}} placeholder
gh issue view <issue-number> | tsk add -t issue-bot -n fix-my-issueNow it's easy to solve GitHub issues with a simple task template. Try this with code reviews as well to easily respond to feedback.
TSK has 3 levels of configuration in priority order:
- Project level in the
.tskfolder local to your project - User level in
~/.config/tsk - Built-in configurations
Each configuration directory can contain:
dockerfiles: A folder containing dockerfiles and layers that are used to create sandboxestemplates: A folder of task template markdown files which can be used via the-t/--typeflag
TSK can be configured via ~/.config/tsk/tsk.toml. All settings are optional.
# Docker container resource limits
[docker]
memory_limit_gb = 12.0 # Container memory limit (default: 12.0)
cpu_limit = 8 # Number of CPUs (default: 8)
# Project-specific configuration (matches directory name)
[project.my-project]
agent = "claude" # Default agent (claude or codex)
stack = "go" # Default stack for auto-detection override
volumes = [
# Bind mount: Share host directories with containers (supports ~ expansion)
{ host = "~/.cache/go-mod", container = "/go/pkg/mod" },
# Named volume: Docker-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 }
]Volume mounts are particularly useful for:
- Build caches: Share Go module cache (
/go/pkg/mod) or Rust target directories to speed up builds - Persistent state: Use named volumes for build caches that persist across tasks
- Read-only artifacts: Mount debugging artifacts, config files, or other resources without risk of modification
Configuration priority: CLI flags > project config > auto-detection > defaults
Each TSK sandbox docker image has 4 main parts:
- A base dockerfile that includes the OS and a set of basic development tools e.g.
git - A
stacksnippet that defines language specific build steps. See: - An
agentsnippet that installs an agent, e.g.claudeorcodex. - A
projectsnippet that defines project specific build steps (applied last for project-specific customizations). This does nothing by default, but can be used to add extra build steps for your project.
It is very difficult to make these images general purpose enough to cover all repositories. You may need some special customization. See dockerfiles for the built-in dockerfiles as well as the TSK custom project layer to see how you can integrate custom build steps into your project by creating a .tsk/dockerfiles/project/<yourproject>.dockerfile or ~/.config/tsk/dockerfiles/project/<yourproject>.dockerfile snippet.
You can run tsk docker build --dry-run to see the dockerfile that tsk will dynamically generate for your repository. You can also run tsk run --type tech-stack or tsk run --type project-layer to try to generate a stack or project snippet for your project, but this has not been heavily tested.
See the Docker Builds Guide for a more in-depth walk through.
I'm working on improving this part of tsk to be as seamless and easy to set up as possible, but it's still a work in progress. I welcome all feedback on how to make this easier and more intuitive!
Templates are simply markdown files that get passed to agents. TSK additionally adds a convenience {{description}} placeholder that will get replaced by anything you pipe into tsk or pass in via the -d/--description flag.
To create good templates, I would recommend thinking about repetitive tasks that you need agents to do within your codebase like "make sure the unit tests pass", "write a commit message", etc. and encode those in a template file. There are many great prompting guides out there so I'll spare the details here.
TSK uses Squid as a forward proxy to control network access from task containers. If you want to customize the proxy configuration e.g. to allow access to a specific service or allow a URL for downloading specific dependencies of your project, you can create a squid.conf file in the user level configuration directory, usually ~/.config/tsk. Look at the default TSK squid.conf as an example.
TSK uses the following directories for storing data while running tasks:
- ~/.local/share/tsk/tasks.json: The task queue and task definitions
- ~/.local/share/tsk/tasks/: Task directories that get mounted into sandboxes when the agent runs. They contain:
- /repo: The repo copy that the agent operates on
- /output: Directory containing a log file with the agent's actions
- /instructions.md: The instructions that were passed to an agent
This project uses:
cargo testfor running testsjust precommitfor full CI checks- See CLAUDE.md for development guidelines
MIT License - see LICENSE file for details.