Show HN: TSK – agent sandbox, delegation, and parallelization tool

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:

1. Assign tasks to AI agents with natural language descriptions and task type templates to automate prompt boilerplate
2. Agents work autonomously in parallel isolated Docker containers
3. Get git branches back with their changes for review
4. 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!

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.

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

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.
• --description is 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 --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.

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:

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

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

Let's create a very basic way to automate working on GitHub issues:

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.

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:

• dockerfiles: A folder containing dockerfiles and layers that are used to create sandboxes
• templates: A folder of task template markdown files which can be used via the -t/--type flag

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 stack snippet that defines language specific build steps. See:
  • go
  • java
  • lua
  • node
  • python
  • rust
• A project snippet that defines project specific build steps. This does nothing by default, but can be used to add extra build steps for your project.
• An agent snippet that installs an agent, e.g. claude or codex.

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 test for running tests
• just precommit for full CI checks
• See CLAUDE.md for development guidelines

MIT License - see LICENSE file for details.