Codebase Colony

Your codebase is a place.

Codebase Colony turns a real repository into an explorable isometric settlement — directories become districts, files become structures, dependencies become transit, and Git history brings recent work to life.

Current version: 0.3.0

The screenshots below show the packaged app’s sample-colony experience. Run npm start and choose Tour a sample colony to explore it locally.

Version 0.3.0 adds compiler-backed TypeScript/JavaScript analysis, modular language analyzers, existing coverage and test-result artifact support, rename-aware Git signals, persistent trends, confirmed-failure missions, and optional debounced live refresh — building on the developer workflow integrations introduced in 0.2.

No Codebase Colony account, subscription, hosted backend, OAuth app, or paid API is required.

Codebase Colony is an MVP with a complete analysis-to-visualization loop. Its goal is to make repository signals easier to understand without pretending code quality can be reduced to a single score.

Screenshots

Sample colony

Building inspector

Run npm start and choose Tour a sample colony to explore the full visual experience.

What is mapped

Repository signal	Colony representation
Repository	Colony
Directory/module	Bounded district
File	Selectable building
LOC or file size	Building height
Language and file role	Building color and proportions
AST/static-analyzer complexity	Stress crown and inspector metric
TODO/FIXME markers	Construction/debt flag
Resolved module imports	Transit lines
Recent Git activity	Lit windows
Test files	Defensive beacon
Existing coverage artifact	Coverage infrastructure in the inspector
Confirmed existing test failures	Damage lighting, repair signal, and repair mission
Complexity + churn + centrality + debt + size	Transparent hotspot pressure, flicker, and alerts
Circular dependencies	Deadlocked transit loops and emergency route signals
Module activity	Pedestrian density, cranes, lit windows, and service traffic
Inter-district coupling	Traffic volume and overloaded junctions
Healthy mature code	Stable lighting and rooftop gardens—not artificial decay

The layout is deterministic for the same normalized repository analysis. Files are ordered and packed by directory; no random positions are used.

Features

• Native folder selection through Electron
• TypeScript compiler-AST analysis for JavaScript/TypeScript imports, exports, symbols, and decision complexity
• Modular conservative analyzers for Python, Java, Go, and Rust, with explicit fallback disclosure
• Safe bounded reading of existing coverage-summary, Istanbul, LCOV, and Cobertura artifacts
• Safe bounded reading of existing JUnit, Jest, and Vitest result artifacts; tests are never executed
• Deterministic isometric district layout with crisp SVG rendering
• Smooth cursor-centered zoom, drag-to-pan, reset/focus controls, hover feedback, and keyboard-selectable structures
• File and district inspectors that explain exactly why a structure looks the way it does
• Search palette with Ctrl/Cmd+K
• Dependency and Git-activity layers
• Transparent Colony Health factors for maintainability, test presence, documentation, debt signals, and activity
• Friendly degraded mode for folders without Git history and guided sample mode
• Recent-repository resume on the next launch
• Deterministic ambient pedestrians, dependency-driven traffic, drones, streetlights, and atmospheric movement
• Architecture, Health, Activity, Test, and Mission investigation protocols that alter city emphasis
• Dependency-cycle detection with unmistakable circular transit alerts
• Composite hotspot scoring with every contributing factor exposed in the file inspector
• Repository-driven missions with exact targets, metrics, criteria, severity, and expected city effects
• Rescan comparison with before/after health, risk, complexity, coverage, cycles, debt, and mission completion
• Search-to-camera flight, relationship isolation, double-click focus, breadcrumbs, and safe Reveal in Explorer
• Reduced-effects control and automatic prefers-reduced-motion support
• Auto-detected Visual Studio Code, Cursor, and VSCodium integration with a system-default fallback
• Optional movable Mini Colony window with an always-on-top toggle, compact city, live Git signals, repository health, priority missions, and workflow shortcuts
• Repository Navigator with a collapsible directory tree, risk/change/mission filters, and omitted-file access
• Command palette file, directory, filter, and > command modes with full keyboard navigation
• Local Git workspace for status, staging, commits, fetch, and explicitly confirmed non-force pushes
• GitHub repository, Issues, Pull Requests, Actions, commit, file, and branch-comparison shortcuts derived from origin
• Reveal in Explorer, safe terminal launch, relative/full path copying, and quick read-only diffs
• Default-branch comparison with file/addition/deletion totals and affected hotspot identification
• Expanded “What changed?” rescan report covering added/removed files, health/risk, and new/resolved missions
• App-owned, derived-only scan trends and mission achievements with per-repository reset
• Optional debounced live refresh that coalesces filesystem bursts before a read-only rescan
• Rename-aware per-file Git churn within an explicitly disclosed 500-commit window
• Reproducible analysis profiler for evidence-based large-repository tuning
• ? keyboard shortcut overlay

Developer workflow integrations

Open a local repository and use the top-bar Navigator, Editor, Git, and Mini Colony controls. Codebase Colony detects supported editors from PATH and standard Windows install locations. Repository opens use a visible new editor window, while selected files reuse the current editor window. The preferred editor is remembered on this machine only.

Mini Colony can be opened from the top bar, the > command palette, or Ctrl+Shift+M. It sits in the current monitor’s top-right corner, can remain above other windows while you code, and can be moved, resized, unpinned, or closed normally. Its Git status refreshes automatically; the Refresh action explicitly reruns the read-only repository scan.

Git status is read from the selected repository. Stage, unstage, commit, fetch, and push happen only after an explicit user action. Push never force-pushes. Pull and merge resolution are intentionally handed to the preferred editor rather than reimplementing conflict handling in Codebase Colony.

Remote links are derived from a recognized GitHub origin; there is no GitHub API, token storage, or built-in sign-in. Fetch and push use the machine’s existing Git credential configuration and fail with guidance when credentials are unavailable. All visualization, analysis, navigation, editor launch, local staging, and local commits continue to work without a GitHub account.

See Developer integrations and safety, analysis and artifact safety, and the 0.3.0 security review for the exact trust boundaries.

Architecture

Electron main process
  folder dialog + validated IPC + workflow integrations
             │
             ▼
modular repository analyzers
  filesystem ─ AST/language plugins ─ Git ─ artifacts ─ graph/risk ─ health/missions
             │
             ▼
normalized RepositoryAnalysis v2 model
             │ context-isolated preload bridge
             ▼
React renderer
  deterministic city + agent generator ─ SVG simulation ─ investigation/mission UI

• electron/analysis/ contains small analyzer modules with no renderer dependency.
• electron/history.ts stores bounded derived trend snapshots in Electron’s app-owned data directory.
• electron/watcher.ts owns the optional ignored-path-aware, debounced Windows repository watcher.
• src/shared/model.ts is the versioned boundary between analysis and presentation.
• src/city/layout.ts converts only the normalized model into deterministic city geometry.
• src/components/CityCanvas.tsx owns rendering and camera interaction; it never reads the filesystem.
• src/components/Inspector.tsx exposes the real metrics behind each visual signal.
• src/shared/intelligence.ts owns cycle detection, composite risk, and deterministic mission generation.
• src/shared/comparison.ts reevaluates colony state and missions across real rescans.
• electron/integrations.ts owns known-editor launch, local Git state/actions, read-only diffs, branch comparison, and derived GitHub links.
• src/shared/navigation.ts creates deterministic large-repository trees and filtered quick-open results.

This boundary leaves room for new language analyzers, history replay, live watching, and a different rendering implementation without coupling repository access to the UI.

Development

Requirements: Node.js 20+ and Git available on PATH.

npm install
npm run dev       # Vite + Electron development mode
npm start         # production build, then launch Electron
npm run build     # typecheck and build renderer/main process
npm run typecheck
npm run lint
npm test
npm run profile:analysis # reproducible synthetic 1,500-file analyzer profile
npm run pack:win  # unpacked Windows application for fast packaging checks
npm run dist:win  # assisted Windows installer (.exe) in release/

Windows installer

Run npm run dist:win on Windows. The resulting Codebase-Colony-Setup-<version>-x64.exe is written to release/. It is an assisted per-user installer with:

• a selectable installation directory,
• Start Menu and Desktop shortcuts,
• standard Windows uninstall registration,
• preserved application preferences on uninstall,
• a branded application and installer icon.

The development build is unsigned, so Windows SmartScreen may show an “Unknown publisher” warning. Production distribution should add Authenticode signing before publishing the installer.

The tests create temporary Git repositories whose paths contain spaces. They confirm analysis remains read-only and separately verify staging, hook-suppressed commits, fetch, push, diffs, and branch comparison against an isolated local bare remote.

Supported analysis

JavaScript and TypeScript receive compiler-backed analysis through the TypeScript parser:

• static import, export … from, require(), and literal dynamic-import discovery
• relative-import resolution across common JS/TS extensions and index files
• AST decision-point complexity, exported symbol counts, function counts, and class counts
• TODO/FIXME detection
• source/test/config/documentation classification

Python, Java, Go, and Rust use modular conservative static analyzers for imports, visible declarations, and decision signals. These initial plugins do not invoke compilers, language servers, package managers, or repository scripts. Unsupported, oversized, malformed, unknown, and binary files remain represented using safe metadata and Git signals; the inspector identifies partial and fallback results.

Git history is read with argument-safe git -C <path> subprocess calls, follows detected renames backward, and is capped at the latest 500 commits. A repository exceeding that window is marked partial. Generated/heavy directories and symlinks are skipped. Rendering is capped at 1,200 buildings; extra files remain part of aggregate analysis and are disclosed in the UI.

Existing coverage is recognized from coverage-summary.json, Istanbul coverage-final.json, LCOV, and Cobertura XML at fixed conventional paths. Existing test state is recognized from fixed JUnit, Jest, and Vitest result paths. Artifact reads are size- and record-bounded, symbolic-link artifacts are rejected, unsafe XML declarations are rejected, and the app never runs a test command.

Ambient populations are capped independently of repository size: up to 64 pedestrians, 42 vehicles, and 6 drones. They are generated deterministically from district activity and dependency traffic, use browser-native SVG motion rather than per-agent JavaScript loops, and can be disabled instantly.

Analysis boundaries

• Repository scripts, installs, tests, hooks, and application code are not executed during analysis.
• Analysis uses filesystem metadata, source parsing, and bounded Git history.
• Symbolic links are skipped to avoid escaping the selected tree.
• Coverage and test status are parsed only from allowlisted, already-existing bounded artifacts; XML entity/DOCTYPE processing is rejected.
• Electron runs with nodeIntegration: false, context isolation, sandboxed renderer, a narrow preload API, restrictive navigation handling, and a Content Security Policy.
• Workflow IPC accepts only known editor IDs, fixed Git action variants, validated repository-relative paths, and derived GitHub targets. It never accepts arbitrary executables, shell commands, remotes, or URLs.
• App-initiated commits and pushes disable repository hooks and commit signing. Pull, checkout, reset, discard, rebase, stash, force-push, and automatic sync are not exposed.
• Explicit staging may use filters already configured in the user’s local Git installation, just as staging from another Git client would. It is never triggered during analysis or automatically.
• Trend history contains derived metrics and mission IDs only, is capped at 40 scans per repository, stays in Electron’s app-owned local data, and can be reset from the Colony inspector.
• Live refresh is off by default, ignores generated/VCS/dependency/temp paths, coalesces event floods, and performs the same read-only analyzer path as an explicit rescan.

Current limitations

• Risk and mission scores remain directional signals rather than objective quality grades; every contributing factor is shown.
• Python, Java, Go, and Rust support is intentionally conservative rather than full compiler-semantic analysis.
• Git history replay is not yet visualized; history-derived churn is limited to the latest 500 commits.
• Nested directories are individual packed districts rather than a visible parent/child hierarchy.
• The SVG renderer prioritizes polished navigation for small and medium repositories; very large colonies summarize structures above the render cap while retaining mission targets, hotspots, cycle members, and central files. Every analyzed file remains available through navigation and editor actions.
• The current installer targets x64 Windows and is unsigned; automatic updates are not implemented.
• Live refresh targets the supported Windows build and is deliberately opt-in rather than a background service.

Roadmap

Highest-value next steps:

1. Read-only Git history replay so the colony visibly grows through releases and eras.
2. Visible parent/child district hierarchy without destabilizing deterministic packing.
3. Spatial aggregation and additional level-of-detail rendering for repositories above the drawing cap.
4. Full parser-library plugins and richer symbol relationships for Python, Rust, Go, and Java.
5. Trend comparison ranges and exportable derived reports.