Skip to content
Docs
Getting Started

Getting Started

This page takes you from nothing to a first Task handed to a Drudger.

Requirements

  • Linux or macOS. On Windows, run DRUDGE inside WSL.
  • git.
  • Docker Sandboxes with the sbx CLI. Every Drudger runs its agent in an sbx sandbox.
  • One harness for the agents:
    • Claude Code with a login. sbx keeps its own copy of the token, and a host login does not refresh it. When the token inside sbx expires, log in again and re-seed the credentials inside sbx.
    • opencode with a provider the sandbox can reach. See opencode below.

Install 

curl -fsSL https://drgtools.dev/install.sh | sh

The script puts drg in ~/.local/bin, or in /usr/local/bin when run as root. It checks the download against the checksums of the release.

Set DRG_VERSION to install a specific release and DRG_INSTALL_DIR to pick another directory:

curl -fsSL https://drgtools.dev/install.sh | DRG_VERSION=v0.1.0 DRG_INSTALL_DIR="$HOME/bin" sh

With Go installed, you can build it from source:

go install github.com/IgorBolotnikov/DRUDGE/cmd/drg@latest

Set up 

drg setup

In a terminal, drg setup first asks which harness the Drudgers run. Move with ↑ and ↓ or k and j, pick with Enter, and cancel with Esc or Ctrl-C:

Harness
› claude-code (default)
  opencode

The list turns into one line with your answer, like Harness: claude-code.

Then it asks for the model the harness runs and for how many Drudgers may work on one project at once. Type an answer and press Enter, or press Enter alone to take the default in brackets. An answer DRUDGE refuses prints the reason and asks again:

Model the harness runs [harness default]:
Drudgers that may work on one project at once [3]:

Then come three selects. The status of a new task is todo or draft. Pull requests are off by default, and turning them on asks whether to open them as drafts:

Status of a new task
› todo (default)
  draft
Open pull requests
› no (default)
  yes

The last question is the color theme. The rest of the run keeps the colors setup started with, and the picked theme applies from the next command:

Color theme
› system (default)
  nord
  monokai
  catppuccin-mocha
  dracula

drg setup -y, short for --defaults, skips the questions and takes the defaults. A run whose input is not a terminal asks nothing either. See Global config and Theme for the keys the answers set.

It then creates ~/.drudge/ and writes:

  • ~/.drudge/config.json, the global config
  • ~/.drudge/theme.json, the color theme
  • ~/.drudge/tui.json, the TUI config with the default layout of drg tui
  • ~/.drudge/schema/, the JSON schemas both config files, the project config and the TUI config point at
  • ~/.drudge/projects/, where the projects and their Tasks live

It also installs the DRUDGE skill for the configured harness. The skill lets a planning agent write DRUDGE Tasks for you. Only the configured harness gets it:

  • claude-code at ~/.claude/skills/DRUDGE/SKILL.md
  • opencode at ~/.config/opencode/skills/DRUDGE/SKILL.md. This path does not follow XDG_CONFIG_HOME.

A harness switch leaves the skill of the old harness in place.

The schemas and the skill are rewritten on every run. Running drg setup again in a terminal asks the same questions, starting on the values of your config files, and writes the answers back into them. Every key it does not ask about stays as it is. drg setup -y leaves existing config files alone. drg setup never asks about the TUI config and leaves an existing one alone.

First project

Run drg project init in the directory you want the agents to work on, to make it a project:

cd ~/code/uploader
drg project init uploader

A directory that is a git repository becomes the one repository of the project. Otherwise every subdirectory that is a git repository becomes one, and a directory holding none is refused.

In a terminal it then asks how many Drudgers may work on this project at once and whether to open pull requests for it. Every question starts on the value of your global config, so Enter keeps the global value:

Drudgers that may work on this project at once [3]:
Open pull requests
› no (default)
  yes

Turning pull requests on asks whether to open them as drafts. Only the answers that differ from the global config go into the project config. drg project init uploader -y, short for --defaults, skips the questions and keeps the global values. See Project config for the keys.

drg project init writes .drudge/config.json in that directory. Task commands run there work on that project. It prints each repository with the default branch that task branches are cut from. The default branch is read from origin/HEAD. When it shows as unresolved, run git remote set-head origin -a in the repository, or set defaultBranch for it in .drudge/config.json.

First task

Add a Task with drg task new. Its description is the prompt the agent gets:

drg task new --title "Add retry to uploader" --description "Retry a failed upload three times before giving up."

It prints the short id of the Task. A Task created without --status is todo, which is ready to run. Pass --status draft to keep it back for review. --description-file reads a longer description from a file, or from stdin with -.

Hand it to a Drudger:

drg task run 3f9a1c2e

drg task run takes the lowest free slot of the project. A slot with no Drudger yet gets one: a git worktree per repository under .drudge/worktrees/slot-<n>/ and an sbx sandbox over them. An idle Drudger is reused. The Drudger checks out a branch for the Task, starts the agent in its sandbox and returns. drudger.maxConcurrentDrudgers in the global config caps how many Drudgers work on one project at once, and defaults to 3. drg task run 3f9a1c2e --dry-run prints the prompt the agent would get and starts nothing.

Watch it with drg task list, drg task show, drg task runlog and drg task status:

drg task list                # every Task of the project and its status
drg task show 3f9a1c2e       # one Task in full, with what its last run left behind
drg task runlog 3f9a1c2e     # a compact view of the latest run, or --raw for the files the agent wrote
drg task status 3f9a1c2e     # whether the agent is working, stuck or finished

Once the Session has ended, drg task status records the outcome on the Task. A Task that got shit done ends up done, or unmerged while its work is not on the default branch yet. A Task that fucked up ends up fucked-up. A Task the vendor turned away goes back to todo. Mark an unmerged Task done with drg task done once its work is merged.

drg drudger list shows what each Drudger of the project is doing.

opencode

With drudger.harness set to opencode, a Drudger runs opencode in an sbx create opencode sandbox. The agent approves every permission your opencode config does not explicitly deny. The sandbox is the security boundary.

DRUDGE manages no opencode config. Pass yours into the sandbox in OPENCODE_CONFIG_CONTENT. List it in drudger.env of the project config and export it in the shell you run drg in:

export OPENCODE_CONFIG_CONTENT='{"provider":{"ollama":{"npm":"@ai-sdk/openai-compatible","options":{"baseURL":"http://192.168.1.20:11434/v1"},"models":{"qwen3-coder":{}}}}}'

The provider base URL must be reachable from inside the sandbox. 127.0.0.1 inside the sandbox is the sandbox itself, so a provider on 127.0.0.1 of the host does not work. Set drudger.model to provider/model, like ollama/qwen3-coder.

Update and uninstall 

drg update

drg update replaces the binary with the latest release and checks it against the release checksums. A binary built from source is updated by building it again.

drg cleanup

drg cleanup asks before it removes ~/.drudge/ with every project and Task in it. --force skips the question. It leaves the drg binary, the skill under ~/.claude/skills/ or ~/.config/opencode/skills/, the .drudge/ directories of your projects and the sbx sandboxes in place. Remove the sandboxes first with drg drudger nuke <slot> in each project, then delete the binary.

Last updated on
Syncing Tasks