Your Agent understands your project better over time
An open-source desktop app that brings Claude Code, Codex, and other local coding agents into your project workflow
Assign tasks, review plans, trace every change. The conventions and findings that accumulate carry over to the next agent
When each Agent session ends, the code stays. The decisions don't.
- Three days later, you don't know why this line changed. The Agent touched 100+ files, and
git blameonly tells you who committed, not the reasoning behind it. - Two months later, no one knows the design rationale. The Agent picked an architecture direction, and the reason for rejecting the alternatives vanished with the chat window.
- Every new session starts from scratch. The same questions, constraints, and history must be explained to a new Agent instance every time.
- Different Agents contradict each other in the same codebase. Switch agents or start a new session and the architectural leanings, naming habits, and testing approach can all change, with nothing holding them to one line.
These problems share one root cause: Agents lack a persistent, structured governance layer. FylloCode is that layer.
FylloCode sits on top of your existing codebase and toolchain. It does not replace your IDE, CI/CD, or project management system. It adds a layer for using Agents well over time and preserving the context that work produces.
Dev Systems (GitHub / Yunxiao / Jira ...)
↑ writes back results
┌──────────────────────────────┐
│ FylloCode │ ← governance layer
│ fyllo-specs · fyllo-cortex │
│ fyllo-spawn │
└──────────────────────────────┘
↓ constraints & context injection
Coding Agent (any)
↓
your codebase
| Capability | Description |
|---|---|
| Unified standards | The fyllo-specs MCP server exposes Project-owned specs to all Agents, persisting across Workspace sessions and Agent instances |
| Decision archiving | Every proposal's rationale and rejected alternatives are persisted as structured data, not lost in chat history |
| Full traceability | Task → Chat → Proposal → Apply & Archive: every step is recorded as one lineage, from intent to execution |
| Cross-Agent delegation | The current Chat Agent can use fyllo-spawn to send focused work to another installed ACP Agent and inspect synchronous or background spawned Sessions |
| Project overview | Each Workspace opens to an overview page aggregating governance status, active changes, recent lineage threads, and spec/guideline evolution by Project |
| Self-evolving rules | fyllo-cortex maintains Project guidelines and Workspace knowledge, injects their context into sessions, and prompts Agents to maintain conventions at key stages |
| Writes back to dev systems | Task results sync back to your existing project management tools without creating another silo |
FylloCode moves every coding task along a single line, each phase with defined inputs, outputs, and constraints. Every step records its input, decisions, and artifacts as one lineage, and what gets settled feeds straight into the next task.
That line is not a fixed pipeline. After Task and Chat, the execution path depends on the nature of the change:
Task ──────▶ Chat ──────▶ Triage ────────▶ Apply & Archive
Intent Refine & │ Constrained
entry decide │ execution & archive
│
├─ Direct Clear scope, no contract change
├─ Plan Needs thinking through, contract intact
└─ Proposal Changes an API, schema, or visible behavior
The three paths are not separate entry points but an escalation within the same discussion: decide whether a Plan is needed, and if the Plan turns out to touch a contract, escalate to a Proposal. Whichever path you take, it lands on the same lineage.
The entry point of the line. A task can be created directly or synced in from a connected dev system (GitHub / Yunxiao / Jira ...). FylloCode imposes no process here. This is where a unit of work enters the governed flow and becomes the shared anchor for everything that follows.
This is where the approach takes shape. Facing a concrete task, the Agent analyzes the requirement, gathers evidence
from the codebase, and guides you through the tradeoffs until you converge on a decision together. It does not
produce a plan out of thin air. fyllo-specs injects the relevant Project spec state from the Workspace so the discussion stays within
the right boundaries from the start. The reasoning, including the options that were ruled out, is captured as part of
the lineage instead of vanishing in a chat window.
The heaviest of the three paths, taken only when a change affects a public API, schema, protocol, storage format, user-visible behavior, or a responsibility boundary. A small change with clear scope goes straight to implementation, and one that needs thinking through but leaves contracts intact gets a session-level Plan. Neither produces the review artifacts below.
Once a decision is reached, the Agent turns it into reviewable, structured artifacts. Output is driven by OpenSpec and customizable per project. The default is four structured artifacts:
proposal.md: background, new capabilities, changed capabilities, affected modulesdesign.md: Goals and Non-Goals, final decisions on open questions with justifications for rejected alternatives, change risksspecs: spec entries extracted from this change, written back to the project knowledge basetasks.md: detailed task breakdown by file and function, with acceptance criteria, including whether guidelines need to be updated
These four artifacts form the Proposal review and preserve the record that remains two months later when someone asks why the system was designed this way.
The Agent executes under fyllo-specs constraints. Architecture boundaries, naming conventions, and restricted
operations are enforced in real time during coding, not caught later in code review. Execution is strictly scoped to what
tasks.md approved: changes outside that boundary are blocked, ensuring the actual diff matches the reviewed plan. Each
task runs in an isolated Git worktree by default, keeping the main branch clean until the task is reviewed and merged,
and multiple tasks can run in parallel at different stages without blocking each other.
Once the change lands, the complete record is automatically archived: code change scope, decision context, spec
updates, guidelines evolution, and a refreshed project health score. Part of this feeds back into fyllo-specs and
fyllo-cortex as background knowledge for the next task. This closes the lineage so the next Task no longer starts from
scratch. The rest syncs to your existing dev systems without creating another tool silo.
FylloCode works with any API-compatible model. Different phases make different demands on model capability. From practical experience:
-
Chat and Proposal benefit from stronger reasoning models. Claude Opus or GPT-Sol are good choices. The Agent needs to deeply understand the project context, weigh tradeoffs across multiple approaches, and make defensible design decisions. Model reasoning quality directly affects how credible and reviewable the output is.
-
Apply can run on smaller, faster models. By this point, task boundaries are precisely defined by
tasks.md, and the Agent's job is closer to structured execution than open-ended reasoning. Smaller models work well here, with the added benefit of lower cost.
A common pairing: Opus for Chat and Proposal, Sonnet or Haiku for Apply.
A typical Agent session has two inputs: the current code and this session's prompt.
Before it writes any code, a FylloCode Agent has access to:
- The current code (from your repository)
- Project specs (from
fyllo-specs: architecture constraints, naming conventions, restricted operations) - Historical decision context (why this module was designed this way, which directions were ruled out)
- Change history (what problem was being solved the last time this area was touched)
- Evolving guidelines (from
fyllo-cortex, continuously evaluated and maintained through the task flow)
It retains both the reason the project evolved and the current implementation.
Sustaining a project over time means turning the conventions you settle on, the conclusions an investigation finally
reached, and the background only you have, into structured context that agents can use directly in the next task.
fyllo-cortex handles this through two separate tools.
Guidelines (engineering conventions, committed with the code). New Chat / Apply sessions receive an index of
guidelines/**/*.md and the Agent reads the full text on demand. Chat, Proposal, Apply, Archive, and Project Health
Check prompts ask the Agent to decide whether a guideline should be initialized, created, or repaired. Conventions
follow real changes instead of drifting in a hand-maintained document.
Knowledge (facts you cannot derive from the repository, Workspace-level). When the Agent hits a counterintuitive
finding, an investigation that cost far more than its answer, or an instruction from you that reaches beyond the current
task, it places a knowledge.flag card. Flagging does not interrupt the discussion, and the entry is written only
after you confirm it, keeping its source and date so it can be re-checked when it ages.
This mechanism addresses one core problem: how engineering knowledge accumulates through Agent collaboration instead of being reset at the end of every session.
Sustained maintenance of complex projects requires every change to leave modified code and decision traces that future Agents and engineers can understand. FylloCode's architecture is built around this.
We're actively expanding knowledge accumulation across more dimensions. Guidelines are the starting point.
Task results can be written back to existing dev systems to maintain toolchain continuity.
| System | Status |
|---|---|
| Yunxiao | ✅ First integration |
| TAPD | 🔄 Planned |
| GitHub | 🔄 Planned |
| GitLab | 🔄 Planned |
| Linear | 🔄 Planned |
| Jira | 🔄 Planned |
| PingCode | 🔄 Planned |
| Coding DevOps | 🔄 Planned |
| Layer | Technology |
|---|---|
| Client | Electron · Vue 3 · TypeScript |
| Agent protocol | Agent Client Protocol (ACP) |
| Spec server | fyllo-specs (MCP Server enhanced on top of OpenSpec) |
| Cortex server | fyllo-cortex MCP Server |
| Spawn server | fyllo-spawn HTTP-only MCP Server |
Download the installer for your platform from the Releases page:
| Platform | Architecture | Format |
|---|---|---|
| macOS | Apple Silicon / Intel | dmg |
| Windows | x64 | installer |
| Linux | x64 | AppImage · deb |
Repository scanning, git queries, and lineage projection all run locally. No external service is involved.
FylloCode is licensed under MIT. PRs are welcome. Please read CONTRIBUTING.en.md before submitting.
FylloCode is built on top of these open source projects and protocols:
Electron · Vue 3 · TypeScript · Nuxt UI · Tailwind CSS · ACP · MCP · OpenSpec · markstream-vue
LinuxDO: Sincere · Friendly · United · Professional