How singhcoder/claude-code works
1. What this repository is
This is a Python-first porting workspace, not a finished product runtime. The active code in src/ exists to model, inspect, and compare a rewritten Claude Code-style harness against archived snapshots and a remembered subsystem map.
2. Top-level execution boundary
The main user-facing entrypoint is src/main.py, which exposes a small CLI for reporting on the workspace: summary, manifest, subsystems, commands, tools, and parity-audit. That CLI is the primary boundary between the repository’s internal metadata model and human/operator inspection.
3. Core data model layer
src/models.py holds the structured representation of the porting workspace, including subsystem, module, and backlog/state concepts. src/port_manifest.py is the authoritative view of the current Python tree shape, and the query layer renders that into human-readable output.
4. Query and reporting flow
src/query_engine.py and the legacy-named src/QueryEngine.py provide the summary/rendering side of the system. They consume the manifest/model data and produce the status views used by the CLI, so the data flow is: workspace metadata → manifest/models → query engine → CLI output.
5. Command and tool inventories
src/commands.py and src/tools.py capture the ported inventories for command and tool surfaces. These are not just helpers; they are first-class architectural artifacts because the repo is tracking parity of agent-facing capabilities, not only source files.
6. Subsystem namespace mirroring
The many packages under src/—for example assistant, bootstrap, bridge, coordinator, hooks, keybindings, remote, server, skills, state, upstreamproxy, vim, and voice—represent the archived system’s major subsystems. In the current repository they function primarily as a structural mirror and future implementation surface, with the important architectural point being that the tree is organized by subsystem boundaries rather than by a single monolithic app layer.
7. Reference and parity data
src/reference_data/ is the static snapshot layer used to compare the current Python workspace against the archived source shape. It contains subsystem inventories, command/tool snapshots, and archive-surface snapshots, which makes parity checking a data-driven operation rather than a manual inspection task.
8. Verification and audit path
tests/test_porting_workspace.py validates the workspace shape, while python3 -m src.main parity-audit checks the current tree against the stored reference data. This creates a second control plane: runtime code for reporting, and test/audit code for parity verification.
9. Support modules around the core
Modules such as task.py, tasks.py, history.py, context.py, runtime.py, cost_tracker.py, costHook.py, dialogLaunchers.py, and interactiveHelpers.py suggest the repository is also preparing agent-session state, execution context, and interaction utilities. These are support boundaries around the core metadata/query system rather than a conventional application service stack.
10. Overall architecture
The repository is organized as a porting harness: a small Python CLI and query layer sit on top of structured manifests, inventories, and snapshots, while a wide set of subsystem packages preserves the original system’s architectural partitioning. For a diagram, the key boxes are: CLI entrypoint, manifest/model/query core, reference-data parity store, subsystem namespace, and test/audit verification loop.
Main entry points: port_manifest.py Manifest · reference_data Snapshots · main.py CLI · parity_audit.py Parity audit
Components 19
Core reporting
CLI, manifest, models, and query/reporting pipeline.
- CLI · User-facing reporting entrypoint with summary and audit commands.
src/main.py - Query engine · Renders workspace metadata into status and inspection views.
src/query_engine.py - Legacy engine · Legacy-named query engine kept alongside the modern module.
src/QueryEngine.py - Models · Structured representation of subsystems, modules, and state.
src/models.py - Manifest · Authoritative shape of the current Python workspace.
src/port_manifest.py - Commands · Ported command surface inventory used for parity reporting.
src/commands.py - Tools · Ported tool surface inventory used for parity reporting.
src/tools.py
Parity data
Static snapshots used for comparison against the current workspace.
- Snapshots · Static reference data for subsystem, command, and surface comparison.
src/reference_data
Subsystem mirror
Representative subsystem packages that preserve the archived boundary map.
- assistant · Representative mirrored subsystem package.
src/assistant - bootstrap · Representative mirrored subsystem package.
src/bootstrap - bridge · Representative mirrored subsystem package.
src/bridge - coordinator · Representative mirrored subsystem package.
src/coordinator - hooks · Representative mirrored subsystem package.
src/hooks - server · Representative mirrored subsystem package.
src/server - skills · Representative mirrored subsystem package.
src/skills - state · Representative mirrored subsystem package.
src/state - upstreamproxy · Representative mirrored subsystem package.
src/upstreamproxy
Verification
Tests and audit path for workspace shape and parity checks.
- Parity audit · Checks the current tree against stored reference data.
src/parity_audit.py - Workspace test · Validates the workspace shape and reporting assumptions.
tests/test_porting_workspace.py
Connections 33
- CLI → Query engine: uses · CLI renders reporting output through the query layer.
- CLI → Manifest: reads · CLI can report on the workspace manifest.
- CLI → Commands: reports · CLI exposes command inventory views.
- CLI → Tools: reports · CLI exposes tool inventory views.
- CLI → Parity audit: invokes · CLI exposes the parity-audit boundary.
- Query engine → Models: consumes · Reporting is driven by the structured workspace model.
- Query engine → Manifest: consumes · Reporting uses the manifest as the source tree shape.
- Query engine → Legacy engine: mirrors · Legacy and current query engine modules coexist.
- Manifest → assistant: includes · Manifest reflects major subsystem packages.
- Manifest → bootstrap: includes · Manifest reflects major subsystem packages.
- Manifest → bridge: includes · Manifest reflects major subsystem packages.
- Manifest → coordinator: includes · Manifest reflects major subsystem packages.
- Manifest → hooks: includes · Manifest reflects major subsystem packages.
- Manifest → server: includes · Manifest reflects major subsystem packages.
- Manifest → skills: includes · Manifest reflects major subsystem packages.
- Manifest → state: includes · Manifest reflects major subsystem packages.
- Manifest → upstreamproxy: includes · Manifest reflects major subsystem packages.
- Snapshots → Commands: snapshots · Stored snapshots support command parity checks.
- Snapshots → Tools: snapshots · Stored snapshots support tool parity checks.
- Snapshots → Parity audit: drives · Audit logic compares the current tree against snapshots.
- Parity audit → Manifest: compares · Audit checks current tree shape against the manifest.
- Parity audit → Models: compares · Audit uses modeled workspace structure.
- Workspace test → Manifest: validates · Tests verify workspace shape and manifest assumptions.
- Workspace test → Parity audit: covers · Tests cover the parity audit control path.
- Snapshots → assistant: maps · Subsystem snapshots mirror archived boundaries.
- Snapshots → bootstrap: maps · Subsystem snapshots mirror archived boundaries.
- Snapshots → bridge: maps · Subsystem snapshots mirror archived boundaries.
- Snapshots → coordinator: maps · Subsystem snapshots mirror archived boundaries.
- Snapshots → hooks: maps · Subsystem snapshots mirror archived boundaries.
- Snapshots → server: maps · Subsystem snapshots mirror archived boundaries.
- Snapshots → skills: maps · Subsystem snapshots mirror archived boundaries.
- Snapshots → state: maps · Subsystem snapshots mirror archived boundaries.
- Snapshots → upstreamproxy: maps · Subsystem snapshots mirror archived boundaries.