Concepts

MVP Spec

GitHubEdit page

MVP Spec

#Goal

CodeMesh v0 makes agentic development handoff fast and explicit.

Primary workflow:

codemesh agent prepare goggquote --base main --profile codex

Expected result:

  • fresh temporary clone from the correct remote/base
  • source checkout warnings surfaced
  • env readiness checked
  • toolchain readiness reported when policy declares it
  • project docs discovered from the prepared clone
  • ready workspace path and handoff_docs: N count printed
  • run metadata stored for cleanup and audit

#Core Modules

#Project Registry

Owns the canonical workspace view.

Responsibilities:

  • project identity
  • alias conflicts
  • normalized remotes
  • desired local paths
  • present and missing projects
  • scan and add behavior
  • project persistence

Used by:

  • scan
  • add
  • tree
  • status
  • hydrate
  • access
  • agent prepare

#Readiness

Owns project and agent handoff diagnostics.

Responsibilities:

  • present/missing state
  • stale/fetch state
  • dirty source checkout warnings
  • base branch blockers
  • env readiness results
  • toolchain readiness results
  • final warn/block action

Used by:

  • tree
  • status
  • doctor
  • agent prepare

#Env Readiness

Owns secret-free env checks.

Responsibilities:

  • required env files
  • required env keys
  • warn/block mode
  • missing-env diagnostics

Non-responsibilities:

  • reading secret values
  • writing .env files
  • integrating secret backends

Used by:

  • Readiness

#Env Binding

Owns private logical-requirement bindings and fake-provider bundle materialization.

Responsibilities:

  • local private binding metadata
  • logical env key to provider reference mapping
  • allowed-scope intersection
  • fake provider adapter
  • agent-scoped bundle metadata without values

Non-responsibilities:

  • live secret providers
  • storing raw secret values
  • writing repo-local env files

Used by:

  • env bind
  • agent prepare
  • target export

#Workspace Manifest

Owns the portable canonical workspace topology contract.

Responsibilities:

  • deterministic manifest export
  • strict manifest import validation
  • project identity, alias, clone hint, and relative path checks
  • local Project Registry persistence under the importing machine's workspace root
  • secret-free portable metadata

Non-responsibilities:

  • syncing manifests between machines
  • storing operational state outside SQLite
  • cloning project content
  • exporting readiness, dirty/stale state, Agent Runs, machine facts, or env values

Used by:

  • manifest export
  • manifest import
  • bootstrap
  • target export

#Workspace Target Export

Owns target-ready JSON for future cloud, dev, and agent destinations.

Responsibilities:

  • package Workspace Manifest topology
  • include registered machine facts and explicit target facts
  • include scoped Env Binding references without values
  • keep output stable for adapters and tests

Non-responsibilities:

  • live Coder, DevPod, Daytona, or team-service calls
  • provider account mutation
  • raw secret or env value export
  • observed readiness, dirty/stale state, or Agent Run export

Used by:

  • target export

#Toolchain Readiness

Owns toolchain readiness declaration and status reporting.

Responsibilities:

  • repo policy toolchain requirement names
  • present, missing, and unknown status results
  • warn/block diagnostics
  • fake detector support for deterministic proof

Non-responsibilities:

  • installing tools
  • running package-manager setup
  • building development environments

Used by:

  • Readiness
  • doctor
  • Agent Run Contract

#Agent Prep

Owns agent workspace prep.

Responsibilities:

  • resolve project through Project Registry
  • resolve effective project policy
  • run Readiness
  • create temp clone through the selected Clone Strategy
  • checkout requested, policy, remote-default, or main fallback base
  • discover project docs
  • write run metadata
  • return ready path and diagnostics

Used by:

  • agent prepare

#Agent Run Contract

Owns versioned agent run metadata.

Responsibilities:

  • contract version and producer metadata
  • project and checkout provenance
  • selected Clone Strategy metadata
  • readiness diagnostics and handoff docs
  • toolchain status when checked
  • command execution records
  • redaction, validation, JSON encoding/decoding, and file writes
  • State Store metadata shape and run-list projections

Used by:

  • agent prepare
  • agent run
  • runs
  • clean

#Commands

The current runnable command surface is maintained in Command Catalog. Future command ideas in research or roadmap docs are planned until they appear in that catalog and top-level CLI help.

#codemesh init [workspace-root]

Creates ~/.codemesh/codemesh.db and records the default workspace root.

#codemesh scan [workspace-root]

Finds Git repos under the workspace root and adds or updates project records.

#codemesh add <path> [--alias name]

Adds one Git repo to the project index.

Project identity:

  • normalized Git remote URL
  • human alias
  • canonical workspace path
  • current-machine path
  • source: canonical or local-only

#codemesh tree

Shows the canonical workspace index.

States:

  • present
  • missing
  • dirty
  • stale
  • env-missing

Output includes canonical path presence, current-machine path presence, local_only_paths from policy when available, and workspace_state for hydrated, placeholder, missing, or blocked path states. Imported manifest Projects can be shown as canonical and missing before hydration. Local-only scanned Projects remain visible as local-only until manifest topology makes them canonical.

#codemesh status [project] [--base branch] [--json]

Shows readiness detail for one project or the whole index.

Checks:

  • local path exists
  • Git remote exists
  • fetch status
  • dirty source checkout
  • base branch exists
  • optional .codemesh.yml env requirements
  • optional .codemesh.yml toolchain requirements
  • optional .codemesh.yml local-only path classifications
  • optional Command Result JSON output for automation

#codemesh doctor <project> [--base branch] [--strict] [--json]

Preflights whether one registered project is ready for agent handoff without creating a temp clone run directory or recording an Agent Run.

Rules:

  • use Agent Prep handoff readiness semantics
  • report green, warning, or blocked
  • print actionable warning and blocker diagnostics
  • keep warning-only readiness exit-zero by default
  • make warning-only readiness fail with --strict
  • use Command Result JSON when --json is passed

#codemesh hydrate <project>

Clones a missing project into its desired local path through the selected Clone Strategy after the shared Hydration Planner classifies the Project as present, missing, path-conflicted, unsafe, or unknown. Planner JSON carries local-only policy decisions when policy is available. Full clone remains the default; --partial-clone and repeatable --sparse path are explicit Git-native lazy checkout opt-ins.

Can replace an unmodified CodeMesh-owned placeholder with a real checkout. Does not perform path-triggered lazy hydration.

#codemesh access <project>

Lazily hydrates a known Project through explicit command access. It uses the same Hydration Planner and executor as hydrate, can move a missing or unmodified Placeholder Project to hydrated, and reports trigger: command-access plus the before/after workspace-state transition in JSON output.

Does not watch filesystem paths, mount a workspace, start a daemon, sync in the background, or hide Git clone/conflict behavior.

#codemesh bootstrap [--all | project... | <manifest-path>]

Reads registered Projects or Workspace Manifest JSON entries, compares them against the registered local machine workspace root and Project Registry, and prints a plan with planned clone/refusal actions from the same Hydration Planner used by hydrate. --dry-run is explicit preview mode. --placeholders refuses the same blockers, creates registry rows when a manifest is supplied, and writes metadata-only placeholder sentinels. --apply refuses blockers before Git, creates needed parent directories and registry rows when a manifest is supplied, then clones planned missing Projects. Hydration plan JSON includes local-only policy declarations when policy is available.

Rules:

  • requires local machine registration
  • blocks path conflicts before mutation
  • writes honest placeholder directories only when explicitly requested
  • clones only explicit planned missing Projects on --apply
  • does not start a daemon, mount a filesystem, or hydrate lazily on filesystem path access

#codemesh manifest export [--output path]

Writes the registered canonical workspace as one deterministic portable manifest JSON file. The manifest is the reviewable interface between machines; SQLite remains the local operational store.

Rules:

  • requires local machine registration
  • derives desired paths relative to the registered workspace root
  • includes aliases, normalized remotes, clone hints, relative paths, and groups
  • excludes local absolute paths, readiness, machine facts, Agent Runs, env values, and secret values

#codemesh manifest import <path>

Validates a portable manifest and persists Project Registry rows for the importing machine.

Rules:

  • requires local machine registration
  • rejects unsupported schema versions, unknown fields, unsafe clone hints, duplicate topology, and non-relative paths before mutation
  • resolves each desired path under the importing machine's workspace root
  • does not clone project content or create project placeholders
  • marks imported rows as canonical so later scans can update current-machine placement without rewriting desired layout

#codemesh target export <target-name>

Emits a Workspace Target spec for future adapters over local fake or cloud destinations.

Rules:

  • requires local machine registration
  • includes manifest topology, machine facts, target facts, and scoped env binding references
  • does not resolve env values or include secret values
  • does not include readiness, dirty/stale state, or Agent Runs
  • does not call Coder, DevPod, Daytona, or remote providers
  • leaves missing projects visible as missing in tree and status

#codemesh env bind <project> <requirement> --provider fake --ref secret-ref --scope scope

Stores a private binding from a logical env requirement to a provider reference in local state.

Rules:

  • provider-specific references stay outside repo-local Project Policy
  • fake provider only in the current slice
  • scopes are explicit and checked during Agent Prep
  • output names requirements and scopes, not values

#codemesh agent prepare <project> [--base branch] [--profile name]

Creates a temp clone under ~/.codemesh/agents.

Rules:

  • clone from normalized remote
  • use full-clone by default; allow explicit Git-native --partial-clone and repeatable --sparse path opt-ins
  • checkout requested, policy, remote-default, or main fallback base
  • warn if source checkout is dirty
  • warn or block on env based on policy
  • warn or block on toolchain status based on policy
  • resolve default and policy-selected handoff docs from the prepared clone
  • write codemesh-run.json
  • record local-only policy decisions in codemesh-run.json
  • optionally materialize fake-provider env bundles when allowed scopes intersect private bindings
  • print ready path and handoff doc count

#codemesh runs

Lists prepared agent runs.

#codemesh clean [--older-than age]

Deletes old agent runs.

#Policy

Repo-local policy is optional.

File: .codemesh.yml

See Project Policy Reference for the current .codemesh.yml interface, defaults, env readiness behavior, toolchain readiness behavior, include-docs intent, local-only path classifications, and no-secret-values rule.

#State

Local state lives under:

~/.codemesh/
  codemesh.db
  agents/

Initial tables:

  • settings
  • projects
  • machines
  • scans
  • agent_runs

#Implemented MVP Phases

  1. Go module, CLI skeleton, config path handling.
  2. SQLite store and migrations.
  3. Git remote normalization and repo inspection.
  4. Project Registry.
  5. Env Readiness and policy parser.
  6. Readiness.
  7. init, add, scan, tree, status.
  8. Agent Prep, agent prepare, runs, clean.
  9. hydrate.
  10. access.
  11. Machine Registry, machine register, and machine status.
  12. Doctor preflight and strict warning failure.
  13. Fake-provider Env Binding and agent-scoped env bundle metadata.
  14. Toolchain readiness declaration, doctor reporting, and Agent Run Contract status metadata.
  15. Bootstrap topology and clone execution.

#Planned Later

  • multi-machine sync
  • workspace manifest export/import commands for Git-backed desired topology; current code has the internal entry/load slice and bootstrap input
  • synced remote project indexes
  • shared object cache or worktree Clone Strategies
  • live secret providers or env file writing
  • live toolchain provider integrations
  • daemon, mount, UI, automatic placeholders, path-triggered lazy hydration, or file-level lazy hydration

#Non-Goals

  • daemon
  • mount
  • automatic placeholders
  • live secret materialization
  • toolchain installation or environment builds
  • cloud sync
  • UI
  • path-triggered or file-level lazy hydration