{"id":30075161,"url":"https://github.com/dtormoen/tsk","last_synced_at":"2026-02-21T18:11:57.247Z","repository":{"id":300857007,"uuid":"993887001","full_name":"dtormoen/tsk","owner":"dtormoen","description":"Task manager and sandbox for coding agents","archived":false,"fork":false,"pushed_at":"2026-02-17T05:17:55.000Z","size":6796,"stargazers_count":133,"open_issues_count":2,"forks_count":15,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-02-17T08:13:28.534Z","etag":null,"topics":["agentic-coding","agents","ai","ai-agents","ai-agents-automation","claude-code","codex","rust","sandbox"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dtormoen.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-05-31T18:27:41.000Z","updated_at":"2026-02-17T05:17:29.000Z","dependencies_parsed_at":"2025-07-18T07:14:57.104Z","dependency_job_id":"3e6e17d9-157f-4c22-a7da-c96c13c7c23f","html_url":"https://github.com/dtormoen/tsk","commit_stats":null,"previous_names":["dtormoen/tsk"],"tags_count":25,"template":false,"template_full_name":null,"purl":"pkg:github/dtormoen/tsk","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dtormoen%2Ftsk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dtormoen%2Ftsk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dtormoen%2Ftsk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dtormoen%2Ftsk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dtormoen","download_url":"https://codeload.github.com/dtormoen/tsk/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dtormoen%2Ftsk/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29689650,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-21T15:51:39.154Z","status":"ssl_error","status_checked_at":"2026-02-21T15:49:03.425Z","response_time":107,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agentic-coding","agents","ai","ai-agents","ai-agents-automation","claude-code","codex","rust","sandbox"],"created_at":"2025-08-08T14:02:05.162Z","updated_at":"2026-02-21T18:11:57.211Z","avatar_url":"https://github.com/dtormoen.png","language":"Rust","funding_links":[],"categories":["Tooling 🧰","AI Coding Agents","Rust","Adjacent agent systems and specialized experiments","Code \u0026 Developer Tools"],"sub_categories":["Orchestrators","Claude Code","Multiplatform"],"readme":"# TSK - AI Agent Task Manager\n\nA Rust CLI tool that lets you delegate development tasks to AI agents running in sandboxed Docker environments. Get back git branches for human review.\n\nCurrently Claude Code and Codex coding agents are supported.\n\n![TSK Demo](./docs/images/tsk-demo.gif)\n\n## Overview\n\nTSK enables a \"lead engineer + AI team\" workflow:\n1. **Assign tasks** to AI agents using task type templates to automate prompt boilerplate and enable powerful multi-agent workflows\n2. **Agents work autonomously** in parallel isolated Docker containers with file system and network isolation\n3. **Get git branches** back with their changes for review\n4. **Review and merge** using your normal git workflow\n\nThink of it as having a team of engineers who work independently and submit pull requests for review.\n\n## Installation\n\n### Requirements\n\n- [Rust](https://rustup.rs/) - Rust toolchain and Cargo\n- [Docker](https://docs.docker.com/get-docker/) - Container runtime\n- [Git](https://git-scm.com/downloads) - Version control system\n- One of the supported coding agents:\n  - [Claude Code](https://docs.anthropic.com/en/docs/claude-code)\n  - [Codex](https://openai.com/codex/)\n  - Help us support more!\n\n### Install TSK\n\n```bash\n# Install using cargo\ncargo install tsk-ai\n# Or build from source!\ngh repo clone dtormoen/tsk\ncd tsk\ncargo install .\n```\n\n## Quick Start Guide\n\nTSK can be used in multiple ways. Here are some of the main workflows to get started. Try testing these in the TSK repository!\n\n### Interactive Sandboxes\n\nStart 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`.\n\n```bash\ntsk shell\n```\n\nThe `tsk shell` command will:\n- Make a copy of your repo\n- Create a new git branch for you to work on\n- Start a proxy to limit internet access\n- Build and start a docker container with your stack (go, python, rust, etc.) and agent (default: claude) installed\n- Drop you into an interactive shell\n\nAfter 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.\n\nThis 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.\n\n### One-off Fully Autonomous Agent Sandboxes\n\nTSK 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:\n\n```bash\ntsk run --type feat --name greeting --description \"Add a greeting to all TSK commands.\"\n```\n\nSome important parts of the command:\n- `--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.\n- `--name` will be used in the final git branch to help you remember what task the branch contains.\n- `--description` is used to fill in the `{{description}}` placeholder in [feat.md](./templates/feat.md).\n\nSimilar 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.\n\nAfter you try this command out, try out these next steps:\n- Add the `--edit` flag to edit the full prompt that is sent to the agent.\n- Add a custom task type. Use `tsk template list` to see existing task templates and where you can add your own custom tasks.\n  - See the [custom templates used by TSK](./.tsk/templates) for inspiration.\n\n### Queuing Tasks for Parallel Execution\n\nThe 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:\n\n```bash\ntsk server start --workers 4\n```\n\nNow, in another terminal window, we can quickly queue up multiple tasks:\n\n```bash\n# Add a task. Notice the similarity to the `tsk run` command\ntsk add --type doc --name tsk-architecture --description \"Tell me how TSK works\"\n\n# Look at the task queue. Your task `tsk-architecture` should be present in the list\ntsk list\n\n# Add another task. Notice the short flag names\ntsk add -t feat -n greeting -d \"Add a silly robot greeting to every TSK command\"\n\n# Now there should be two running tasks\ntsk list\n\n# Wait for the tasks to finish. After they complete, look at the two new branches\ngit branch --format=\"%(refname:short) - %(subject) (%(committerdate:relative))\"\n```\n\nAfter you try this command out, try these next steps:\n- Add tasks from multiple repositories in parallel\n- Start up multiple agents at once\n  - Adding `--agent codex` will use `codex` to perform the task\n  - 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\n  - Adding `--agent claude,claude` will have `claude` do the task twice. This can be useful for exploratory changes to get ideas quickly\n\n### Task Chaining\n\nChain tasks together with `--parent` (`-p`) so a child task starts from where its parent left off:\n\n```bash\n# First task: set up the foundation\ntsk add -t feat -n add-api -d \"Add a REST API endpoint for users\"\n\n# Check the task list to get the task ID\ntsk list\n\n# Second task: chain it to the first (replace \u003ctaskid\u003e with the parent's ID)\ntsk add -t feat -n add-tests -d \"Add integration tests for the users API\" --parent \u003ctaskid\u003e\n```\n\nChild 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`. Chains of any length (A → B → C) are supported.\n\n### Create a Simple Task Template\n\nLet's create a very basic way to automate working on GitHub issues:\n\n```bash\n# First create the tsk template configuration directory\nmkdir -p ~/.config/tsk/templates\n\n# Create a very simple template. Notice the use of the \"{{DESCRIPTION}}\" placeholder\ncat \u003e ~/.config/tsk/templates/issue-bot.md \u003c\u003c 'EOF'\nSolve the GitHub issue below. Make sure it is tested and write a descriptive commit\nmessage describing the changes after you are done.\n\n{{DESCRIPTION}}\nEOF\n\n# Make sure tsk sees the new `issue-bot` task template\ntsk template list\n\n# Pipe in some input to start the task\n# Piped input automatically replaces the {{DESCRIPTION}} placeholder\ngh issue view \u003cissue-number\u003e | tsk add -t issue-bot -n fix-my-issue\n```\n\nNow it's easy to solve GitHub issues with a simple task template. Try this with code reviews as well to easily respond to feedback.\n\n## Commands\n\n### Task Commands\n\nCreate, manage, and monitor tasks assigned to AI agents.\n\n- `tsk run` - Execute a task immediately\n- `tsk shell` - Start a sandbox container with an interactive shell\n- `tsk add` - Queue a task (supports `--parent \u003ctaskid\u003e` for task chaining)\n- `tsk list` - View task status and branches\n- `tsk clean` - Clean up completed tasks\n- `tsk delete \u003ctask-id\u003e...` - Delete one or more tasks\n- `tsk retry \u003ctask-id\u003e...` - Retry one or more tasks\n\n### Server Commands\n\nManage the TSK server daemon for parallel task execution. The server automatically cleans up completed and failed tasks older than 7 days.\n\n- `tsk server start` - Start the TSK server daemon\n- `tsk server stop` - Stop the running TSK server\n\n### Configuration Commands\n\nBuild Docker images and manage task templates.\n\n- `tsk docker build` - Build required docker images\n- `tsk template list` - View available task type templates and where they are installed\n\nRun `tsk help` or `tsk help \u003ccommand\u003e` for detailed options.\n\n## Configuring TSK\n\nTSK has 3 levels of configuration in priority order:\n- Project level in the `.tsk` folder local to your project\n- User level in `~/.config/tsk`\n- Built-in configurations\n\nEach configuration directory can contain:\n- `dockerfiles`: A folder containing dockerfiles and layers that are used to create sandboxes\n- `templates`: A folder of task template markdown files which can be used via the `-t/--type` flag\n\n### Configuration File\n\nTSK can be configured via `~/.config/tsk/tsk.toml`. All settings are optional.\n\n```toml\n# Docker container resource limits\n[docker]\nmemory_limit_gb = 12.0  # Container memory limit (default: 12.0)\ncpu_limit = 8           # Number of CPUs (default: 8)\n\n# Proxy configuration\n[proxy]\n# Forward ports from containers to host services (agents connect to tsk-proxy:\u003cport\u003e)\n# Default: [] (no port forwarding)\nhost_services = [5432, 6379]  # e.g., PostgreSQL, Redis\n\n# Git-town integration (https://git-town.com/)\n# When enabled, task branches automatically record their parent branch\n[git_town]\nenabled = true  # default: false\n\n# Server daemon configuration\n[server]\nauto_clean_enabled = true   # Automatically clean old tasks (default: true)\nauto_clean_age_days = 7.0   # Minimum age in days before cleanup (default: 7.0)\n\n# Project-specific configuration (matches directory name)\n[project.my-project]\nagent = \"claude\"        # Default agent (claude or codex)\nstack = \"go\"            # Default stack for auto-detection override\nvolumes = [\n    # Bind mount: Share host directories with containers (supports ~ expansion)\n    { host = \"~/.cache/go-mod\", container = \"/go/pkg/mod\" },\n    # Named volume: Docker-managed persistent storage (prefixed with tsk-)\n    { name = \"go-build-cache\", container = \"/home/agent/.cache/go-build\" },\n    # Read-only mount: Provide artifacts without modification risk\n    { host = \"~/debug-logs\", container = \"/debug-logs\", readonly = true }\n]\nenv = [\n    # Environment variables passed to the container\n    { name = \"DATABASE_URL\", value = \"postgres://tsk-proxy:5432/mydb\" },\n    { name = \"REDIS_URL\", value = \"redis://tsk-proxy:6379\" },\n]\n```\n\nVolume mounts are particularly useful for:\n- **Build caches**: Share Go module cache (`/go/pkg/mod`) or Rust target directories to speed up builds\n- **Persistent state**: Use named volumes for build caches that persist across tasks\n- **Read-only artifacts**: Mount debugging artifacts, config files, or other resources without risk of modification\n\nEnvironment variables (`env`) let you pass configuration to task containers, such as database URLs or API keys. Use `tsk-proxy:\u003cport\u003e` to connect to host services forwarded through the proxy.\n\nThe `[proxy]` section lets you expose host services to task containers. Agents connect to `tsk-proxy:\u003cport\u003e` to reach services running on your host machine (e.g., local databases or dev servers).\n\nThe `[git_town]` section enables integration with [git-town](https://www.git-town.com/), a tool for branch-based workflow automation. When enabled, TSK sets the parent branch metadata on task branches, allowing git-town commands like `git town sync` to work correctly with TSK-created branches.\n\nConfiguration priority: CLI flags \u003e project config \u003e auto-detection \u003e defaults\n\n### Customizing the TSK Sandbox Environment\n\nEach TSK sandbox docker image has 4 main parts:\n- A [base dockerfile](./dockerfiles/base/default.dockerfile) that includes the OS and a set of basic development tools e.g. `git`\n- A `stack` snippet that defines language specific build steps. See:\n  - [default](./dockerfiles/stack/default.dockerfile) - minimal fallback stack\n  - [go](./dockerfiles/stack/go.dockerfile)\n  - [java](./dockerfiles/stack/java.dockerfile)\n  - [lua](./dockerfiles/stack/lua.dockerfile)\n  - [node](./dockerfiles/stack/node.dockerfile)\n  - [python](./dockerfiles/stack/python.dockerfile)\n  - [rust](./dockerfiles/stack/rust.dockerfile)\n- An `agent` snippet that installs an agent, e.g. `claude` or `codex`.\n- A `project` snippet 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.\n\nIt is very difficult to make these images general purpose enough to cover all repositories. You may need some special customization. See [dockerfiles](./dockerfiles) for the built-in dockerfiles as well as the [TSK custom project layer](./.tsk/dockerfiles/project/tsk.dockerfile) to see how you can integrate custom build steps into your project by creating a `.tsk/dockerfiles/project/\u003cyourproject\u003e.dockerfile` or `~/.config/tsk/dockerfiles/project/\u003cyourproject\u003e.dockerfile` snippet.\n\nYou 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.\n\nSee the [Docker Builds Guide](docs/docker-builds.md) for a more in-depth walk through, and the [Network Isolation Guide](docs/network-isolation.md) for details on how TSK secures agent network access.\n\nI'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!\n\n### Creating Templates\n\nTemplates 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.\n\nTo 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.\n\n### Custom Proxy Configuration\n\nTSK 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](./dockerfiles/tsk-proxy/squid.conf) as an example.\n\n## TSK Data Directory\n\nTSK uses the following directories for storing data while running tasks:\n- **~/.local/share/tsk/tasks.db**: SQLite database for task queue and task definitions\n- **~/.local/share/tsk/tasks/**: Task directories that get mounted into sandboxes when the agent runs. They contain:\n  - **\u003ctaskid\u003e/repo**: The repo copy that the agent operates on\n  - **\u003ctaskid\u003e/output**: Directory containing a log file with the agent's actions\n  - **\u003ctaskid\u003e/instructions.md**: The instructions that were passed to an agent\n\n## Contributing\n\nThis project uses:\n- `cargo test` for running tests\n- `just precommit` for full CI checks\n- See [CLAUDE.md](CLAUDE.md) for development guidelines\n\n## License\n\nMIT License - see [LICENSE](LICENSE) file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdtormoen%2Ftsk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdtormoen%2Ftsk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdtormoen%2Ftsk/lists"}