                                 ___    _    ____
                                / _ \  / \  / ___|
                               | | | |/ _ \| |
                               | |_| / ___ \ |___
                                \___/_/   \_\____|

              O P E N   A G E N T   C O N T R I B U T I O N

Put your spare AI tokens to work. Contribute to open source — automatically.

Getting Started · How It Works · Commands · Configuration · Architecture · Contributing

The Problem

You pay for AI agent tokens every month. Claude Code, Codex, OpenCode — they all come with token budgets. But most days, you don't use them all. Those leftover tokens? Wasted.

Meanwhile, thousands of open source repos have TODOs nobody finishes, lint warnings nobody fixes, tests nobody writes, and issues nobody picks up.

The Solution

OAC bridges the gap. Point it at a repo, and it will:

Scan the codebase for actionable tasks (TODOs, lint issues, missing tests, open GitHub issues)
Estimate token costs and pick tasks that fit your remaining budget
Execute the work using your AI agent of choice — in parallel, sandboxed environments
Submit pull requests, link issues, and track every contribution

# Install globally
npm install -g @open330/oac

# That's it. One command.
oac run --repo facebook/react --tokens 50000

# Or run without installing
npx @open330/oac run --repo facebook/react --tokens unlimited

  ✔ Resolved facebook/react
  ✔ Repository ready at ~/.oac/cache/repos/facebook/react
  ✔ Analyzed 12 modules, 847 files, 23 findings
  ✔ Created 4 epic(s)
  ✔ Epic token estimation completed
  [oac] Selected 3 epic(s) for execution, 1 deferred.

  ✔ Improve test coverage for reconciler (1/3)
      PR #1847: https://github.com/facebook/react/pull/1847
  ✔ Fix lint warnings in scheduler (2/3)
      PR #1848: https://github.com/facebook/react/pull/1848
  ✔ Address TODO comments (3/3)
      PR #1849: https://github.com/facebook/react/pull/1849

  Run Summary (Epic Mode)
    Epics completed: 3/3
    PRs created:     3
    Tokens used:     38,420 / 50,000
    Duration:        8m 42s

Features

	Feature	Description
Scan	Task Discovery	Finds TODOs, lint issues, test gaps, dead code, and open GitHub issues
Budget	Token Estimation	Per-provider token counting with knapsack-optimized task selection
Run	Parallel Execution	Run 2-3 agents simultaneously in isolated git worktrees
Retry	Resume Failed	`--retry-failed` re-runs only tasks that failed in the previous run
Ship	PR Automation	Creates PRs with timeout protection, links issues, notifies webhooks
Track	Contribution Logs	Git-native audit trail in `.oac/` — who contributed what, with how many tokens
Rank	Leaderboard	See who's recycling the most tokens across your team
Explain	Task Inspector	`oac explain <id>` shows why a task was selected and what the agent will do
Complete	Shell Integration	Tab-completion for bash, zsh, and fish shells

Quick Start

Prerequisites

Node.js >= 20 (see engines in package.json)
git installed
At least one AI agent CLI: Claude Code, Codex, or OpenCode

Install

# From npm (recommended)
npm install -g @open330/oac

# Or use without installing
npx @open330/oac --help

# From source (for contributors)
git clone https://github.com/Open330/open-agent-contribution.git
cd open-agent-contribution
pnpm install
pnpm build

Setup

# Interactive setup wizard
oac init

# Or quick start without wizard
oac init --minimal --repo owner/repo

   ___    _    ____
  / _ \  / \  / ___|
 | | | |/ _ \| |
 | |_| / ___ \ |___
  \___/_/   \_\____|

 Welcome to Open Agent Contribution.
 Let's put your spare tokens to work.

? Select your AI providers: › Claude Code, Codex CLI
? Monthly token budget for OAC: › 100000
? Add your first repo (owner/repo): › facebook/react

✔ Config written to oac.config.ts
✔ Created .oac/ tracking directory
Ready! Run 'oac doctor' to verify or 'oac run' to start.

Verify

oac doctor

  Environment Check
  ─────────────────
  [✔] Node.js     v24.0.0
  [✔] git         v2.43.0
  [✔] GitHub Auth  gh authenticated as @jiun
  [✔] Claude CLI   v1.0.16
  [✘] Codex CLI    not found

  4/5 checks passed

Commands

Command	Description
`oac init`	Interactive setup wizard — creates `oac.config.ts` (`--minimal` for quick start)
`oac doctor`	Verify environment (Node, git, agents, auth)
`oac analyze`	Deep codebase analysis — builds module context, groups findings into epics
`oac scan`	Quick task discovery — finds actionable items without building full context
`oac plan`	Show execution plan with token budget breakdown
`oac run` (alias: `oac r`)	Primary command. Full pipeline: analyze → plan → execute → PR → track
`oac status`	Show running/recent job status
`oac log`	View contribution history
`oac leaderboard`	Show contribution rankings
`oac completion`	Generate shell tab-completion scripts (bash/zsh/fish)
`oac explain <id>`	Show why a task/epic was selected and what the agent will do

`oac analyze` — Deep Codebase Analysis

oac analyze --repo owner/repo [--force] [--format table|json]

Builds a full codebase map (modules, files, exports, dependencies), runs all scanners, groups findings into epics, and persists everything to .oac/context/. The analysis is cached — subsequent runs only re-analyze changed files (incremental via git diff).

`oac run` — The Main Event

oac run \
  --repo owner/repo \       # Target repository
  --tokens 50000 \          # Token budget (or "unlimited")
  --provider claude-code \  # AI agent to use (claude-code or codex)
  --concurrency 2 \         # Parallel agents (default: 2)
  --mode new-pr \           # Create PRs (or: direct-commit)
  --dry-run \               # Preview without executing (with colored diff)
  --quiet \                 # Suppress spinner/progress output (for CI)
  --retry-failed            # Re-run only previously failed tasks

# Run with unlimited budget
oac run --repo owner/repo --tokens unlimited --provider codex

# Auto-analyzes if no context exists (or use --force to re-analyze)
# Shorthand alias: oac r

Exit Codes:

Code	Meaning
`0`	All tasks/epics completed successfully (or dry-run)
`1`	Unexpected / unhandled error
`2`	Configuration or validation error
`3`	All selected tasks/epics failed
`4`	Partial success — some tasks succeeded, others failed

`oac scan` — Quick Task Discovery

oac scan --repo owner/repo --format table

┌─────────┬──────────────────────────────────┬────────┬──────────┬────────────┐
│ ID      │ Title                            │ Source │ Priority │ Complexity │
├─────────┼──────────────────────────────────┼────────┼──────────┼────────────┤
│ a1b2c3  │ Fix unused import in utils.ts    │ lint   │ 85       │ trivial    │
│ d4e5f6  │ TODO: Add input validation       │ todo   │ 72       │ simple     │
│ g7h8i9  │ Missing tests for Parser class   │ test   │ 68       │ moderate   │
│ j0k1l2  │ Remove dead code in legacy/      │ dead   │ 45       │ simple     │
│ #142    │ Fix date formatting bug          │ issue  │ 91       │ moderate   │
└─────────┴──────────────────────────────────┴────────┴──────────┴────────────┘
  5 tasks discovered

Configuration

OAC uses a TypeScript config file:

// oac.config.ts
import { defineConfig } from "@open330/oac";

export default defineConfig({
  repos: ["facebook/react", "vercel/next.js"],

  execution: {
    provider: "claude-code",  // or "codex"
    concurrency: 2,
    mode: "new-pr",
    taskTimeout: 300,
    tokenBudget: 100_000,     // or "unlimited"
  },

  discovery: {
    scanners: {
      lint: true,
      todo: true,
      testGap: true,
    },
    issueLabels: ["good-first-issue", "help-wanted", "bug"],
  },

  analyze: {
    autoAnalyze: true,         // auto-analyze before run
    staleAfterMs: 86_400_000,  // re-analyze after 24h
  },
});

📖 Full reference: See docs/config-reference.md for every option, type, default, and constraint — auto-generated from the Zod schema.

Architecture

┌─────────────────────────────────────────────────────┐
│                   oac CLI / Dashboard                │
└────────────────────────┬────────────────────────────┘
                         │
              ┌──────────▼──────────┐
              │    Core Engine       │
              │  (Event Bus + Config)│
              └──┬──┬──┬──┬──┬──┬──┘
                 │  │  │  │  │  │
    ┌────────────┘  │  │  │  │  └────────────┐
    │               │  │  │  │               │
┌───▼───┐  ┌───────▼──▼──▼───────┐  ┌───────▼───────┐
│ Repo  │  │  Discovery → Budget  │  │   Tracking    │
│Select │  │  → Execution         │  │  (.oac/ logs) │
└───────┘  └─────────┬───────────┘  └───────────────┘
                     │
              ┌──────▼──────┐
              │  Completion  │
              │ (PR + Issue) │
              └──────┬──────┘
                     │
           ┌─────────▼─────────┐
           │   GitHub / Linear  │
           │   / Jira           │
           └───────────────────┘

Modules

Published as a single package @open330/oac:

Module	Path	Description
Core	`src/core/`	Event bus, config (Zod), types, errors, memory pressure monitoring
Repo	`src/repo/`	GitHub repo resolution, shallow cloning, metadata cache
Discovery	`src/discovery/`	Codebase analyzer (streaming for large files), epic grouper, backlog, scanners (lint, TODO, test-gap, GitHub issues)
Budget	`src/budget/`	Token estimation (tiktoken), complexity analysis, execution planner, resettable counters
Execution	`src/execution/`	Agent adapters (Claude Code, Codex), worktree sandbox, worker
Completion	`src/completion/`	PR creation (Octokit) with timeout protection, diff validation, issue linking
Tracking	`src/tracking/`	Contribution logs, leaderboard, JSON schema
CLI	`src/cli/`	11 commands: init, doctor, analyze, scan, plan, run, status, log, leaderboard, completion, explain. Run module decomposed into 8 focused sub-modules

Tech Stack

Layer	Technology
Runtime	Node.js 24+, TypeScript 5.7+, ESM
Build	pnpm, tsup
CLI	Commander.js, chalk, ora, cli-table3
Concurrency	p-queue for bounded parallelism, memory pressure monitoring
Process	execa for child process management
Git	simple-git, git worktrees for isolation
GitHub	@octokit/rest
AI Agents	Claude Code (`claude-code`), Codex CLI (`codex`) — pluggable via `AgentProvider`
Dashboard	Fastify + embedded SPA with SSE streaming
Quality	Vitest, Biome

Contribution Tracking

Every run creates a JSON log in .oac/contributions/:

.oac/
├── contributions/
│   ├── 2026-02-17-143052-jiun.json
│   ├── 2026-02-17-151023-jiun.json
│   └── 2026-02-18-091500-alice.json
└── leaderboard.json

Each log records: who contributed, which tasks, tokens used, PRs created, and execution metrics. The leaderboard aggregates across all contributors.

oac leaderboard

  Contribution Leaderboard
  ────────────────────────
  #1  jiun     42 tasks   284,000 tokens   38 PRs merged
  #2  alice    31 tasks   195,000 tokens   27 PRs merged
  #3  bob      18 tasks   122,000 tokens   15 PRs merged

How It Works

OAC uses a context-first architecture: it first deeply analyzes the codebase, then groups related findings into coherent epics (not tiny per-file tasks), and executes each epic as a single unit with full module context.

You run `oac run`
        │
        ▼
   ┌─────────┐     Shallow clone, cache metadata
   │  Repo    │────────────────────────────────────┐
   │  Select  │                                    │
   └────┬─────┘                                    │
        │                                          │
        ▼                                          ▼
   ┌─────────┐     Auto-detect src dir,      ┌──────────┐
   │ Analyze │──── module map, exports, ────▶│ Context  │
   └────┬────┘     LOC, dependencies         │ .oac/    │
        │                                    └────┬─────┘
        ▼                                         │
   ┌─────────┐     TODO, lint, test-gap,     ┌────▼─────┐
   │  Scan   │──── GitHub issues ──────────▶│ Findings │
   └────┬────┘                              └────┬─────┘
        │                                        │
        ▼                                        ▼
   ┌─────────┐     Group by module+type,     ┌──────────┐
   │  Group  │──── create coherent units ──▶│  Epics   │
   └────┬────┘     (1 PR per epic)           └────┬─────┘
        │                                        │
        ▼                                        ▼
   ┌─────────┐     Per-epic estimation,      ┌──────────┐
   │ Budget  │──── priority-based select ──▶│   Plan   │
   └────┬────┘                              └────┬─────┘
        │                                        │
        ▼                                        ▼
   ┌─────────┐     git worktree per epic    ┌──────────┐
   │Execute  │──── with module context ────▶│ Results  │
   └────┬────┘                              └────┬─────┘
        │                                        │
        ▼                                        ▼
   ┌─────────┐     Validate diff,           ┌──────────┐
   │Complete │──── create PR, link issue ──▶│   PRs    │
   └────┬────┘                              └────┬─────┘
        │                                        │
        ▼                                        ▼
   ┌─────────┐     .oac/contributions/      ┌──────────┐
   │  Track  │──── JSON audit log ─────────▶│  Done!   │
   └─────────┘     update backlog           └──────────┘

Epic-Based Execution vs Per-Task

	Old (per-task)	New (epic-based)
Unit	1 task = 1 file change	1 epic = N related changes
Context	Agent sees only target file	Agent sees full module context
PR	1 PR per file	1 PR per epic (multi-file)
Persistence	None — re-scans every run	Backlog persisted in `.oac/context/`
Incremental	Full re-scan	Only re-analyzes git-changed files

Supported AI Agents

Agent	Status	Provider ID
Claude Code	Supported	`claude-code`
Codex CLI	Supported	`codex`
OpenCode	Planned	`opencode`
Custom	Implement `AgentProvider` interface	any string

Adding a Custom Agent

import type { AgentProvider } from '@open330/oac-execution';

export class MyAgentAdapter implements AgentProvider {
  readonly id = 'my-agent';
  readonly name = 'My Custom Agent';

  async checkAvailability() { /* ... */ }
  execute(params) { /* ... */ }
  async estimateTokens(params) { /* ... */ }
  async abort(executionId) { /* ... */ }
}

Roadmap

2026.2.17 — Core engine, CLI, 5 scanners, parallel execution, npm publish
2026.2.18 — Context-first architecture: codebase analyzer, epic grouper, incremental analysis, backlog persistence, enhanced prompts with module context
2026.4.x — Claude Code + Codex CLI adapters, token usage reporting, auto-detect sourceDir
2026.4.x — 9-wave quality cycle: performance fixes, UX polish, run module decomposition, shell completion, retry, exit codes, memory monitoring, streaming analysis, config reference docs
Next — OpenCode adapter, multi-agent routing, localhost dashboard, daemon mode
Future — Linear/Jira webhooks, plugin system, sparse checkout for monorepos

Contributing

We welcome contributions! OAC is designed to contribute to repos — and it can contribute to itself too.

# Clone and setup
git clone https://github.com/Open330/open-agent-contribution.git
cd open-agent-contribution
pnpm install
pnpm build

# Run tests
pnpm test

# Lint and format
pnpm lint
pnpm format

# Or just let OAC contribute to itself
npx @open330/oac run --repo Open330/open-agent-contribution --tokens unlimited

See CONTRIBUTING.md for detailed guidelines.

Troubleshooting

Agent not found / command not found

OAC dispatches work to external agents (claude, codex). Make sure the agent CLI is installed and on your PATH:

# Verify agents are reachable
oac doctor

# Check individual agents
which claude   # Claude Code
which codex    # Codex CLI

If oac doctor reports a missing agent, install it following the agent's own documentation, then re-run oac doctor.

Token budget exceeded / nothing was executed

The planner reserves 10% of your budget as a safety margin. If every discovered task exceeds the effective budget, nothing will be selected.

# Check what would be selected
oac run --dry-run --repo owner/repo

# Increase the budget
oac run --tokens 200000 --repo owner/repo

# Or set it in oac.config.ts
export default defineConfig({
  budget: { totalTokens: 200_000 },
});

Config file errors

# Validate your config
oac doctor

# Regenerate a minimal config
oac init --minimal --repo owner/repo

Common issues:

Missing repos array — at least one repo is required.
Invalid provider ID — must be "claude-code" or "codex".
budget.totalTokens must be a positive number.

See docs/config-reference.md for all options.

Permission denied / GitHub auth errors

OAC uses gh (GitHub CLI) for PR creation and issue access. Make sure you're authenticated:

gh auth status
gh auth login   # if not authenticated

For private repos, ensure your token has repo scope.

Sandbox / worktree errors

OAC creates git worktrees in a temporary directory for each task. If a previous run crashed, stale worktrees may remain:

# List worktrees
git worktree list

# Clean up stale entries
git worktree prune

Philosophy

"Don't let your tokens go to waste."

Every month, developers around the world leave millions of AI tokens on the table. OAC turns that idle capacity into real open source contributions — automatically, safely, and transparently.

No hosted services. No data collection. No lock-in. Just your machine, your tokens, and your repos.

Built with spare tokens by the Open330 community.

Report Bug · Request Feature · Discussions

FAQs

What is @open330/oac?

Is @open330/oac popular?

Is @open330/oac well maintained?

Package last updated on 20 Feb 2026

Did you know?

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

@open330/oac

The Problem

The Solution

Features

Quick Start

Prerequisites

Install

Setup

Verify

Commands

oac analyze — Deep Codebase Analysis

oac run — The Main Event

oac scan — Quick Task Discovery

Configuration

Architecture

Modules

Tech Stack

Contribution Tracking

How It Works

Epic-Based Execution vs Per-Task

Supported AI Agents

Adding a Custom Agent

Roadmap

Contributing

Troubleshooting

Philosophy

Related posts

Suno Breached via Shai-Hulud Worm, Leaked Code Exposes AI Music Scraping

Next.js moves to scheduled security releases

`oac analyze` — Deep Codebase Analysis

`oac run` — The Main Event

`oac scan` — Quick Task Discovery