oss-triage-agent

Run AI coding agents against GitHub issues — triage them, then implement fixes in an isolated sandbox.

go install github.com/harsh-m-patil/oss-triage-agent@latest

Make sure ~/go/bin is on your PATH.

Before you start

You need three things set up once:

Requirement	Why
opencode on PATH	Runs the coding agent
GITHUB_TOKEN env var	Reads issues, posts comments, applies labels
OPENCODE_API_KEY env var	Required by some models (check your OpenCode config)

Point the CLI at a git clone whose origin is a GitHub repo:

cd /path/to/your-project   # must have remote.origin.url → github.com/owner/repo
export GITHUB_TOKEN=ghp_...

Create the required labels on the target repo once:

oss-triage-agent setup --repo .

Labels: bug, enhancement, needs-triage, needs-info, ready-for-agent, ready-for-human, wontfix, agent:in-progress

See CONTEXT.md for what each label means.

Quick start

# See what needs triage
oss-triage-agent triage

# Triage one issue (assess, comment, apply labels)
oss-triage-agent triage --issue 42

# Implement a ready-for-agent issue
oss-triage-agent build --issue 42 --repo .

Pass an issue as a flag (--issue 42) or positional argument (42). You can also use a full issue URL.

Shorthand: oss-triage-agent --issue 42 runs triage without typing the subcommand.

Triage

Triage reads an issue, explores the repo with OpenCode, posts a comment, and updates category/state labels. No human approval step — one command does it all.

# List open issues that are unlabeled or marked needs-triage
oss-triage-agent triage

# Triage a specific issue
oss-triage-agent triage --issue 42
oss-triage-agent triage --issue 42 --repo /path/to/clone

Useful flags:

Flag	Default	Description
--repo	.	Git clone to explore (resolves GitHub owner/repo from origin)
--sandbox	nosandbox	nosandbox (host) or docker
--model	opencode/big-pickle	Model passed to OpenCode
--idle-timeout	5m	Cancel if the agent stops producing output

The agent comment is prefixed with > *This was generated by AI during triage.*

Build

Build implements an issue end to end: worktree, agent run, issue comment, lock/unlock.

oss-triage-agent build --issue 42 --repo .

# Local dev without Docker
oss-triage-agent build --issue 42 --sandbox nosandbox

Useful flags:

Flag	Default	Description
--repo	.	Target git repository
--sandbox	docker	docker or nosandbox
--model	opencode/big-pickle	Model passed to OpenCode
--variant, --agent	—	Forwarded to OpenCode
--dangerously-skip-permissions	false	OpenCode permission bypass
--idle-timeout	5m	Cancel if the agent stops producing output

What happens:

1. Records the default-branch HEAD
2. Creates a worktree at .agent/worktrees/issue-<N>-<slug>
3. Adds agent:in-progress to the issue
4. Runs OpenCode in the sandbox
5. Posts a success or failure comment
6. Removes the lock label

Plan

oss-triage-agent plan --issue 42

Not implemented yet. Use triage to assess issues and build to implement them.

Agent debug

Run OpenCode directly and print normalized JSON events — useful for testing models and stream parsing:

oss-triage-agent agent run --prompt "Summarize this repo"
echo "What changed?" | oss-triage-agent agent run

Troubleshooting

GITHUB_TOKEN is not set — Export a token with repo scope before running workflows.

read remote.origin.url — Run from a git clone with origin pointing at GitHub.

github api: 422 on labels — Run oss-triage-agent setup --repo . to create missing labels.

Agent exits immediately — Check opencode is on PATH and OPENCODE_API_KEY is set if your model requires it.

Documentation

Doc	Contents
CONTEXT.md	Domain glossary, label contract, git conventions
docs/architecture.md	Package layout, design, implementation status
docs/sdk.md	Using the Go library (orchestrator, sandboxes, git)

Build and test

go build -o oss-triage-agent .
go test ./...

CI runs go test ./... on push and pull requests (see .github/workflows/ci.yml).

License

See repository license file when present.