ArchiCode is a graph-native software engineering harness for investigating, researching, planning, building, debugging, and evolving software with AI agents.
The architecture graph is the living source of truth and the shared language between engineer and agents. Research conversations, implementation plans, source changes, tests, run history, and review decisions all stay connected to that durable model instead of disappearing into separate tools or ephemeral chat transcripts.
Investigate → Research → Plan → Build → Debug → Verify → Resync
AI can now produce code faster than an engineer can reconstruct the intent, boundaries, and consequences behind it. Traditional IDEs remain file-first, while most agent harnesses remain chat-first. Files expose the details; chat captures a moment. Neither naturally gives you the durable big picture needed to supervise a large and continuously changing AI-built system.
ArchiCode makes the graph the working contract between humans and agents. It connects architecture, design flows, code evidence, decisions, implementation scope, and verification state in one observable workspace. You can move from a system-level view down to a source relationship, ask the Research agent to investigate or design a change, review its plan, let the build harness implement it, and follow every run, diff, test, failure, and approval back to the graph.
This is not only a diagramming, analysis, or planning layer. It is an end-to-end alternative to chat-first coding harnesses. ArchiCode can use Codex, Claude, or API providers as its engines while it owns the persistent project context, orchestration, observability, and human review around them.
ArchiCode is under active development, but its core engineering loop already works: inspect an existing codebase, research and shape its architecture, queue scoped implementation, edit and test source, debug failures, verify outcomes, and reconcile the living graph as the code changes.
- Research and investigation agent — reason at project, flow, subflow, or node scope using the graph, local files, images, documents, web research, durable memory, and specialist subagents.
- AI build harness — turn an approved direction into scoped planning, source changes, tests, debugging, verification, artifacts, and human review rather than stopping at a suggestion.
- Graph as living source of truth — keep architecture intent, implementation evidence, decisions, status, and acceptance checks in the shared model used by both engineers and agents.
- End-to-end observability — inspect the queue, plans, tool activity, traces, logs, source diffs, failures, verification evidence, token usage, and review decisions behind agent work.
- Evidence-backed codebase maps — import an existing repository into architecture perspectives backed by real files, symbols, imports, calls, and source locations.
- Editable 2D architecture canvas — model components, features, tasks, settings, groups, dependencies, and nested detail flows.
- Multi-layer 3D exploration — navigate root flows and nested architecture layers without losing their spatial relationship.
- Architecture knowledge maps — inspect relationship-derived functional communities, trace edges to source evidence, and drill into project-wide code detail.
- Reviewable graph proposals — turn research into explicit node, edge, note, flow, acceptance-check, or implementation actions before anything changes.
- Code and graph resync — reconcile architecture after external edits using deterministic, affected-scope updates and auditable reports.
- Acceptance and policy checks — attach executable criteria to architecture nodes and surface deterministic architecture-policy findings.
- Local-first project memory — keep portable planning state under
.archicode/while credentials and runtime-only data stay machine-local. - Provider and tool choice — use Codex or Claude locally, OpenAI-compatible or Anthropic-compatible APIs, project skills, and MCP servers.
- Practical project tooling — browse files, inspect diffs, operate Git, run local services, debug failures, and export diagrams or project data.
The 3D view turns root and detail flows into navigable layers. Active and overview modes make it easier to understand how a high-level capability expands into deeper implementation structure.
The architecture lens groups related concepts into functional neighborhoods. Select a relationship to see its origin, confidence, verification state, freshness, and supporting source location.
Research chat stays scoped to the relevant graph context. It can investigate project evidence, retain decisions and todos, and return a concrete change set for approval. Approved implementation work then moves through the build harness—planning, source changes, tests, debugging, verification, and review—without severing the connection to the architecture that requested it.
ArchiCode requires Node.js 22.12 or newer and npm.
npm install
npm run devThe renderer development server runs at http://localhost:42873/, and Electron opens the desktop workspace.
npm run typecheck
npm test
npm run buildTo regenerate the four deterministic README screenshots:
npm run visual-qa:readmeThe command writes review copies to artifacts/visual-qa/ and publishes the stable README images under docs/assets/. Electron screenshot capture may need to run outside a restricted sandbox.
npm run pack
npm run dist:mac
npm run dist:win
npm run dist:storepack creates an unpacked application under release/. macOS notarization runs when the required Apple credentials are present; local builds otherwise skip it.
Each project is a normal folder with a .archicode/ directory. Portable project metadata, flows, and ledgers are readable and Git-friendly; machine-local settings, credentials, runs, caches, and generated artifacts are kept out of source control by default.
See TECHSPEC.md for the complete process architecture, storage contracts, importer and resync pipeline, knowledge-map model, agent orchestration, provider behavior, security boundaries, and test matrix.
Created and maintained by Roy Massaad.
ArchiCode is open-source software released under the GNU Affero General Public License, version 3 only (AGPL-3.0-only). Commercial use, modification, distribution, and sale are permitted subject to the AGPL, including its source-availability and network-use requirements.
A separate commercial license is available for organizations that need different terms, including closed-source distribution.
See LICENSE, LICENSING.md, and NOTICE.
External contributors must accept the Individual Contributor License Agreement. If an employer or another organization owns the contribution, an authorized representative must also execute the Corporate Contributor License Agreement.
Read CONTRIBUTING.md before opening a pull request. Contributors retain ownership while granting the rights needed for ArchiCode's public AGPL and commercial editions.
