Inspiration
What it does
How we built it
CodeWeaver
AI-native multi-agent system that autonomously understands, evolves, and verifies your codebase from natural language tasks.
About the Project
Inspiration
Every developer knows the frustration of diving into an unfamiliar codebase. Hours spent tracing imports, deciphering undocumented functions, hunting down where a change needs to go. Existing tools help in isolation — Copilot completes your line, linters catch syntax errors, ChatGPT answers general questions — but none connect the full cycle of understand → plan → modify → verify. We wanted to build an AI-native system that could do all four, autonomously, with the same structured thinking a senior engineer brings to a codebase.
What We Learned
Building CodeWeaver taught us that agent orchestration is fundamentally different from single-call LLM usage. The key insight: specialization beats general intelligence at scale. A single agent asked to analyze, plan, write, and verify code produces shallow results. But when we decomposed those responsibilities across four agents — Analyst, Engineer, Verifier, Coordinator — each with a focused role and structured output schema, the quality of every phase improved dramatically.
We also learned that structured communication between agents is critical. Passing unstructured prose between agents leads to context loss. By enforcing JSON schemas at each handoff (analysis → plan → changes → verification → report), we maintained precision across the entire workflow. The Coordinator agent's job became less about doing work and more about maintaining this structured context across phases — a pattern we believe generalizes far beyond codebase management.
Another lesson: autonomous code modification requires safety guardrails. The Verifier agent isn't optional — it's the mechanism that prevents the system from making incorrect changes. Closing the loop with a validation phase turned CodeWeaver from a one-shot code generator into a self-correcting system.
Formal Framework
We model CodeWeaver as a function composition over specialized agent transformations. Each agent $\mathcal{A}_i$ is defined by a tuple:
$$ \mathcal{A}_i = \langle R_i, I_i, O_i, S_i, T_i \rangle $$
where $R_i$ is the role prompt, $I_i$ the input schema, $O_i$ the output schema, $S_i$ the skill set, and $T_i$ the available tools.
The full workflow is a sequential composition:
$$ \text{Report} = \mathcal{A}{\text{coord}} \circ \mathcal{A}{\text{ver}} \circ \mathcal{A}{\text{eng}} \circ \mathcal{A}{\text{ana}} \circ \mathcal{A}_{\text{coord}}(\text{Task}) $$
The Coordinator maintains a cumulative context state $S_t$ at each step $t$:
$$ S_{t+1} = S_t \cup {a_t}, \quad a_t = \mathcal{A}_t(S_t) $$
where $a_t$ is the structured output produced by the agent at step $t$. This ensures every downstream agent has full visibility into prior decisions.
The Verifier defines a decision function $V$ over the set of files $F$:
$$ V(C_{\text{orig}}, C_{\text{mod}}) = \begin{cases} \text{PASS}, & \text{if } \forall f \in F: \text{syntax}(f) \land \text{complete}(f) \land \neg \text{regression}(f) \[4pt] \text{FAIL}, & \text{otherwise} \end{cases} $$
Each agent produces output in a constrained JSON space $\mathcal{J}$, enforcing structure at every handoff:
$$ a_t \in \mathcal{J} \subset {\text{JSON objects with schema } O_t} $$
This replaces ambiguous natural-language handoffs with typed, verifiable interfaces between agents — the architectural pattern we believe generalizes beyond code.
How We Built It
CodeWeaver is built on the OpenAI API with gpt-4o-mini, structured around four specialized agents defined in AGENTS.md and five reusable skills in skills.md:
Coordinator Agent — Decomposes the user's natural language task into subtasks, delegates to the appropriate agents, maintains running context in a history buffer, and aggregates results into a final report.
Analyst Agent — Discovers all relevant source files, reads their contents, and produces a structured JSON analysis covering architecture summary, key components, patterns detected, potential issues, and a dependency graph.
Engineer Agent — Takes the analysis and original task, produces a change plan with ordered steps, target files, risk assessment, then generates the actual modified code for each file.
Verifier Agent — Diffs original vs. modified code, checks for regressions, validates task completeness, and produces a pass/fail verdict with recommendations.
The workflow is linear but stateful: each agent receives the outputs of all previous agents, enabling rich context-aware decisions. The codeweaver.py engine handles file discovery, content reading, LLM calls with structured JSON response formats, and safe file writing.
Challenges Faced
The hardest challenge was parsing and validating the LLM's structured output. When an agent returns malformed JSON (which happens), the system needs to degrade gracefully rather than crash. We implemented a fallback that wraps raw text into a predictable schema, but this remains an area for improvement — perhaps with constrained decoding or few-shot formatting examples.
A second challenge was determining the right level of abstraction for file changes. The Engineer agent's plan might say "add error handling to function X", but translating that into an actual edit requires reading the function, understanding its context, and generating syntactically valid code that matches existing style. We solved this by having the Engineer agent produce the full modified file content rather than a diff — trading efficiency for reliability.
Finally, managing context windows across the full workflow is non-trivial. Each agent call sends the accumulated history, which grows linearly with workflow phases. For large codebases, we had to strategically include file contents by reference (file index) rather than by value in later stages. Future work could implement a sliding window or retrieval-augmented generation over the codebase.
Quick Start
1. Clone and setup
git clone <your-repo-url>
cd OpenAI_Developer_Platform_Demo
2. Add your API key
Create or open .env and add:
OPENAI_API_KEY=sk-your-key-here
3. Install dependencies
pip install openai python-dotenv
4. Run CodeWeaver
py main.py status # Show codebase overview
py main.py analyze . # Analyze codebase architecture
py main.py plan "Add error handling" . # Generate change plan
py main.py run "Add docstrings" . # Full workflow
py main.py interactive # Interactive session
Architecture
AGENTS.md → 4 specialized agent definitions
skills.md → 5 reusable skill definitions
codeweaver.py → Core engine: agent orchestration, file I/O, LLM interface
main.py → CLI entry point with analyze/plan/run/interactive commands
Agent Workflow
User Task
│
▼
┌──────────────┐
│ Coordinator │ Decompose task
│ Agent │ into subtasks
└──────┬───────┘
│
▼
┌──────────────┐
│ Analyst │ Scan codebase,
│ Agent │ understand architecture
└──────┬───────┘
│
▼
┌──────────────┐
│ Engineer │ Plan changes,
│ Agent │ generate code
└──────┬───────┘
│
▼
┌──────────────┐
│ Verifier │ Validate changes,
│ Agent │ check regressions
└──────┬───────┘
│
▼
┌──────────────┐
│ Coordinator │ Aggregate results,
│ Agent │ produce final report
└──────────────┘
Original Demo Bots
This repository also includes two single-agent demo bots for comparison:
mentor_bot.py— Hackathon mentor advisorinnovation_bot.py— Product innovation advisor
These demonstrate the baseline single-prompt approach that CodeWeaver's multi-agent architecture builds upon.
Log in or sign up for Devpost to join the conversation.