Codebus

Local, versioned repository knowledge with safe staged Refresh and read-only MCP access for developers and AI coding agents.

Comment

Inspiration

Understanding an unfamiliar repository is expensive, and that understanding usually disappears when the task ends. Developers and coding agents repeatedly rediscover the same architecture, while conventional documentation drifts away from the code. Codebus turns that temporary mental model into durable, reviewable project knowledge.

What it does

Codebus creates an Obsidian-compatible Markdown knowledge vault beside a repository. It mirrors source through a privacy filter, drives an installed coding-agent CLI to generate structured concepts, entities, modules, processes, and synthesis pages, and stores every goal or repair in the vault's own Git history.

Developers can create goals, ask read-only questions, run multi-turn chat, generate quizzes, lint or repair the knowledge base, and safely Refresh it after the source changes. A local read-only MCP server exposes vault_list, wiki_list, wiki_search, and wiki_read so Codex and other coding agents can reuse accumulated knowledge without receiving the privacy-filtered raw-source mirror.

Unlike a disposable AI chat or a static documentation export, Codebus treats repository understanding as a living, versioned artifact with an explicit trust boundary and a recovery path.

Build Week scope

Codebus existed before OpenAI Build Week and was developed primarily with Claude Code. This submission does not claim that Codex created the entire product.

During Build Week, Codex with the exact model identifier gpt-5.6-sol drove two substantial extensions:

  1. Safe staged Refresh across Core, CLI, and the Tauri desktop application.
  2. Codex security hardening and measurable Windows isolation evidence.

The public Git history separates these competition-period additions from the pre-existing product, and the primary Codex session is supplied through the required /feedback Session ID.

Safe staged Refresh

Refresh reuses the vault's saved analysis goal. Version 3.2.1 performs a safe staged full rebuild rather than claiming true incremental analysis.

When the deterministic source fingerprint changes, Codebus verifies the managed vault, creates a sibling staging copy, regenerates the wiki in staging, runs structural, citation, and content validation, and promotes the result only after every required check passes. The previous vault becomes a timestamped backup. Quiz history is preserved.

If the source has not changed, Refresh returns a no-op without a model call or a new backup. Generation, validation, or live-vault-change failures occur before promotion and leave the active vault untouched. Promotion uses a recovery journal, and an incomplete automatic restoration returns an explicit recovery-required result with the real paths involved.

The desktop Refresh action consumes the mapped Core RefreshEvent stream through Tauri. It displays real checking, staging, generation, validation, promotion, no-op, backup, success, rollback, and recovery states instead of inventing a second frontend state machine.

How Codex advanced the project

Earlier Claude Code work established the product, but it had not resolved safe Refresh or one of the hardest Windows security questions: whether a coding agent could be proven to read only the selected workspace.

Codex with gpt-5.6-sol traced the existing Rust and Tauri paths, designed Refresh around data-preservation invariants, implemented the Core and UI flows, added regression tests, and exercised real CLI and desktop paths. It also conducted bounded Windows experiments against real Codex 0.144.5 behavior: Shell environment inheritance, authentication-store readability, sibling-repository access, ACL effects, network boundaries, configuration failure modes, and an AppContainer bootstrap path.

That investigation did not produce a deployable hard-isolation backend. Codex instead implemented an immediate credential-inheritance mitigation, ruled out false solutions, converted observations into machine-readable evidence, and kept the production classification at partial. A negative result became useful engineering evidence rather than an unsupported security claim.

How gpt-5.6-sol is used inside Codebus

Codebus drives the installed Codex CLI through a provider-neutral agent layer. In the demonstrated Codex 0.144.5 configuration, gpt-5.6-sol performs substantive product work during Refresh: the existing Goal profile regenerates and repairs managed wiki content, Fix handles deterministic-lint repair, and Verify performs content review and re-review. Sanitized runtime evidence records the configured model, outcome, and isolation classification.

Other providers remain supported, but the submitted workflow and evaluator instructions pin the exact gpt-5.6-sol catalog identifier.

How we built it

Codebus is a Rust workspace with a Tauri backend and a React/TypeScript desktop interface. Its repository scanner produces a filtered source mirror; structured prompts guide knowledge generation; nested Git supplies audit history and recovery; and the MCP server provides a narrow read-only retrieval surface. The same Core operations serve the CLI and desktop application.

Security and trust

Codebus prevents its active Azure provider credential binding from being inherited by Codex Shell descendants and records redacted isolation evidence. The current Windows classification remains partial. Codebus does not claim that Codex can read only the selected workspace because filesystem hard-read isolation, authentication-store isolation, and a production hard-isolation backend have not passed the required gates.

Potential impact

Codebus targets developers onboarding to unfamiliar systems, maintainers returning to old repositories, teams preserving architectural knowledge, and coding agents that need reusable context. It reduces repeated repository exploration while keeping generated knowledge local, inspectable, versioned, and recoverable.

Challenges

  • Keeping CLI and desktop behavior aligned across multiple agent providers.
  • Rebuilding stale knowledge without risking the last known-good vault.
  • Preserving generated quiz history while replacing managed wiki content.
  • Separating credentials required by the Codex control plane from Shell descendants.
  • Distinguishing requested policy, observed runtime behavior, and proven isolation.
  • Clearly separating the pre-existing Claude Code-built product from Build Week Codex work.

Accomplishments

  • A working repository-to-wiki product with privacy filtering and independent Git history.
  • Safe staged Refresh with no-op detection, validation-before-promotion, backups, rollback protection, and desktop progress.
  • Read-only multi-vault MCP access for coding agents.
  • A concrete Codex Shell credential-inheritance fix.
  • Machine-readable isolation evidence with an honest partial classification.
  • A public Windows 3.2.1 installer and a reproducible evaluator path that requires no source build.

What we learned

Security configuration names are not evidence. Agent tooling must distinguish requested policy, observed behavior, and proven boundaries. We also learned that generated documentation becomes valuable only when it is structured, versioned, refreshable, reusable by tools, and honest about failure and recovery.

What's next

The next Refresh step is true incremental impact analysis and complete cross-process operation locking. For hard isolation, Codebus will evaluate AppContainer or a dedicated Hyper-V/VM-style guest runtime against the same filesystem, credential, process, network, configuration, functionality, and cleanup matrix. The product will report hard only after every gate passes against a real runtime identity.

Built With

Share this project:

Updates