OSS-Dev
A Gemini-powered CLI that turns open source contribution into a guided seven-phase workflow — repo analysis, issue intake, planning, verified implementation and PR — with safety approvals and GSSoC-grade governance.
- Role
- Creator & Maintainer
- Year
- 2026
- Category
- AI / Open Source
- Platform
- CLI
- Stack
- PythonTyperClickRichPydanticGeminiMCPuv
- Links
Why I built this
Open source contribution is needlessly hard: new contributors face unclear starting points, complex workflow mechanics and overwhelming codebases. OSS-Dev automates the research, planning, implementation and submission phases of a contribution — originally built for a Gemini hackathon, then transformed into a GSSoC-ready contributor operating system with full governance (contributing guide, security policy, code of conduct, CI with secret scanning).
How it works
Agentic loop with tool calling
Streams LLM chat completions with tool calls across a configurable max-turns budget, validates every tool call gets a result, injects loop-breaker prompts on detected repetition, and emits typed events the CLI/TUI render in real time.
Seven-phase OSS workflow
Repository understanding → issue intake → planning → implementation → verification → validation → commit & PR, with branch-level memory persisted under .oss-dev/branches/.
~30 tools, from shell to GitHub
Built-in tools (read/write/edit file, shell, grep, glob, web search/fetch, todo, memory) plus OSS tools: fetch/list issues, create PRs, git branch/commit/push/rebase/merge, repository analysis and a workflow orchestrator.
Safety approval gates
A command-classification layer blacklists dangerous commands, enforces path containment inside the working directory, and applies approval policies: AUTO, NEVER, ON_REQUEST, ON_FAILURE and YOLO.
Sessions, checkpoints and MCP
Context compression, token tracking and tool-output pruning, with /save, /resume, /checkpoint, /restore commands and MCP server integration.
Key decisions
The architecture mandates strict layering (CLI → Service → Core → Provider) with explicit import rules and provider ABC contracts behind a registry — after a 1,085-line god module proved convention alone fails.
A missing confirmation callback used to return True — a dangerous default. The redesign makes request_confirmation raise when no callback is registered, and blacklists dangerous commands by regex.
The GSSoC transformation (README, CONTRIBUTING, SECURITY, CODE_OF_CONDUCT, ROADMAP, FAQ, issue/PR templates, CI with Gitleaks) made the repo submission-ready and attracted external contributors.
Backend architecture
Modular monolith with strict layering
CLI never contains business logic; Service orchestrates; Core implements; Providers plug in through contracts. Plus Intelligence, Plugin and Config layers, all documented in ARCHITECTURE.md.
Deterministic workflow state machine
IDLE → REPO_ANALYSIS → ISSUE_ANALYSIS → PLANNING → IMPLEMENTATION → VERIFICATION → VALIDATION → COMMIT_PR → COMPLETE, with a BLOCKED state, guarded transitions and JSON persistence per workflow.
Provider abstraction
Typed ABC contracts for GitHub, Git and LLM providers behind a ProviderRegistry — Gemini via its OpenAI-compatible API as the primary model, with tool-call validation at the core.
Layered config
System → User → Project → Env configuration in TOML with OSS_DEV_* environment variables at highest priority, modeled with Pydantic and side-effect free.
Challenges
God module and split-brain state
The workflow module mixed orchestration, validation, prompt generation and git ops, while three separate files managed workflow state. Fixed through a documented decomposition plan with feature-parity gates.
Broken async approval flow
A synchronous confirmation callback used in async contexts with a missing await, and request_confirmation returning True when no callback was set — a dangerous default that shipped early.
Scope limitations
Single-repo operation, only six detected languages, hardcoded test commands instead of CI parsing, and no post-PR review handling or containerized workspace isolation.
What I learned
Architecture boundaries must be enforced by contracts, not convention.
Safety defaults must be fail-closed — mutating actions always pass an approval manager.
Governance-first engineering pays off for OSS adoption and attracts contributors.
Code snippets
async for event in self.agent.run(message):
if event.type == AgentEventType.TEXT_DELTA:
content = event.data.get("content", "")
if not assistant_streaming:
self.tui.begin_assistant()
assistant_streaming = True
self.tui.stream_assistant_delta(content)
elif event.type == AgentEventType.TEXT_COMPLETE:
final_response = event.data.get("content")
if assistant_streaming:
self.tui.end_assistant()
assistant_streaming = False