FylloCode
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
中文 ·
Docs ·
Download
---
## Background
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 blame` only 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.
---
## Core Mechanism
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 |
---
## Workflow
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.
### Task
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.
### Chat
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.
### Proposal
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 modules
- `design.md`: Goals and Non-Goals, final decisions on open questions with justifications for rejected alternatives,
change risks
- `specs`: spec entries extracted from this change, written back to the project knowledge base
- `tasks.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.
### Apply & Archive
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.
---
## Model Selection
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.
---
## What an Agent Knows Before It Changes Your Code
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.
---
## Knowledge Accumulation
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.
---
## Integrations
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 |
---
## Architecture
| 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 |
---
## Installation
Download the installer for your platform from the [Releases](https://github.com/Fioooooooo/FylloCode/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.
## Contributing
FylloCode is licensed under MIT. PRs are welcome. Please read [CONTRIBUTING.en.md](CONTRIBUTING.en.md) before
submitting.
## Acknowledgements
FylloCode is built on top of these open source projects and protocols:
[Electron](https://www.electronjs.org) · [Vue 3](https://vuejs.org) · [TypeScript](https://www.typescriptlang.org) · [Nuxt UI](https://ui.nuxt.com) · [Tailwind CSS](https://tailwindcss.com) · [ACP](https://agentclientprotocol.com) · [MCP](https://modelcontextprotocol.io) · [OpenSpec](https://github.com/Fission-AI/OpenSpec) · [markstream-vue](https://github.com/Simon-He95/markstream-vue)
## License
[MIT](LICENSE)
## Community
[LinuxDO](https://linux.do/): Sincere · Friendly · United · Professional