Skip to content

Make Edgebase an automatic work-contract runtime #3

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ychampion merged 1 commit into from
May 26, 2026
Merged

Make Edgebase an automatic work-contract runtime #3

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 17 additions & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,23 @@

## Unreleased

### Added

- `edgebase bootstrap` for copy-focused, host-aware onboarding prompts.
- Host capability table covering Claude Code, Codex, Cursor, Gemini CLI, OpenCode, and Windsurf setup surfaces.
- Active Work Contract state at `.edgebase/session/active-goal.json`, written by prompt hooks and `edgebase goal --record`.
- `edgebase status` for active goal, freshness, changed files, stale files, elevated tests, unrecorded required checks, and latest artifacts.
- `edgebase finish` for writing `.edgebase/passports/latest.md` and `.json` without inventing test results.
- Codex global skill surfaces for `/edgebase`, `/edgebase-goal`, `/goal`, and `/edgebase-*` commands when global setup is selected.
- Marker-bounded `edgebase team init optional|required` and `edgebase team disable`.

### Changed

- Pre-edit hooks now use the persisted active Work Contract before falling back to preflight state.
- Claude pre-edit checks warn by default and support opt-in strict denial for missing/stale contracts or protected-path edits.
- Git freshness hooks now cover `post-commit`, `post-checkout`, `post-merge`, and `post-rewrite`.
- Patch Passport output now separates inferred required checks from explicitly recorded tests.

## 0.1.9 - 2026-05-26

### Added
Expand Down
58 changes: 39 additions & 19 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
</p>

<p align="center">
<strong>Git-native preflight context for coding agents.</strong>
<strong>Automatic work-contract runtime for coding agents.</strong>
</p>

<p align="center">
Expand All @@ -15,16 +15,19 @@

# Edgebase

Edgebase is a local, git-native preflight layer for coding agents. It records a small, source-backed Goal Capsule before an agent edits, keeps `AGENTS.md` minimal, and serves fresh context through MCP and agent hooks.
Edgebase is a local, git-native work-contract runtime for coding agents. Install it once, and supported agents automatically record a source-backed Goal Capsule before work, check the active Work Contract before edits, refresh context after changes, and finish with a Patch Passport.

Its flagship feature is **Goal Capsules**: short, executable briefs that tell Codex, Claude Code, Cursor-style agents, and human reviewers what to read, what not to touch yet, what tests matter, and what evidence the final patch must include.
Its flagship workflow is **Goal Capsules + active Work Contracts + Patch Passports**: short, executable briefs that tell Codex, Claude Code, Cursor-style agents, and human reviewers what to read, what not to touch yet, what tests matter, and what evidence the final patch must include.

## What It Does

- Records a Goal Capsule before coding agents plan or edit.
- Blocks broad edits when the capsule is missing or stale.
- Prints pasteable `edgebase install-prompt` and `edgebase bootstrap` prompts for Claude Code, Codex, Cursor, Gemini CLI, OpenCode, and Windsurf.
- Records a Goal Capsule and active Work Contract before coding agents plan or edit.
- Warns before unsafe edits by default, with opt-in strict blocking for stale contracts or protected paths.
- Shows an advisory Change Blast Radius for likely routes, migrations, tests, downstream modules, and side-effect risks.
- Refreshes the graph after edits, commits, and MCP calls.
- Refreshes the graph after edits, commits, checkouts, merges, rebases, and MCP calls.
- Shows active workflow state with `edgebase status`.
- Writes final Patch Passports with `edgebase finish`.
- Keeps generated structure out of `AGENTS.md`.
- Runs locally with no Docker, cloud service, graph database, or API key.
- Preserves provenance for every edge: path, line, extractor, confidence, commit, and freshness.
Expand Down Expand Up @@ -86,7 +89,7 @@ edgebase_fork_plan(message, from_id?, branch?, path?, allow_dirty?, budget?)
edgebase_resume(snapshot_id?)
```

The companion context output remains a compact, source-backed capsule: high-signal files, symbols, imports, conservative call edges, inferred tests, owners, churn, freshness, and provenance. Claude Code and Codex project setup also get an automatic preflight gate, so users do not need to remember a special phrase before each task.
The companion context output remains a compact, source-backed capsule: high-signal files, symbols, imports, conservative call edges, inferred tests, owners, churn, freshness, and provenance. Claude Code and Codex project setup also get an automatic work-contract runtime, so users do not need to remember a special phrase before each task.

Edgebase is not a vector database, a Neo4j wrapper, or a generic memory product. It is a small local substrate for answering:

Expand Down Expand Up @@ -117,14 +120,26 @@ Flat instruction files such as `AGENTS.md`, `CLAUDE.md`, and Cursor rules are st
Generate the copy/paste setup prompt for a specific agent:

```bash
python3 -m pip install --user --upgrade git+https://github.com/ychampion/edgebase.git
python3 -m edgebase install-prompt --agent all
python3 -m edgebase install-prompt --agent claude
python3 -m edgebase install-prompt --agent codex
```

Paste this into Claude Code, Codex, Cursor, Gemini CLI, OpenCode, Windsurf, or any coding agent with shell access:
Paste that prompt into Claude Code, Codex, Cursor, Gemini CLI, OpenCode, Windsurf, or any coding agent with shell access. It tells the agent to install Edgebase, run `edgebase setup --scope both`, run `edgebase doctor --scope both`, and report exactly what became automatic.

If Edgebase is not installed yet and you want a one-shot prompt to paste directly:

```text
Set up Edgebase in this repo: current working directory. Install it from https://github.com/ychampion/edgebase, run the local setup and doctor checks yourself, preserve existing agent config, do not commit, and report exactly what changed.
Install Edgebase for this repository and verify the automatic work-contract runtime.

Run:
python3 -m pip install --user --upgrade git+https://github.com/ychampion/edgebase.git
python3 -m edgebase setup --scope both --agents all
python3 -m edgebase doctor --scope both --agents all
python3 -m edgebase status --json

After setup, report exactly which capabilities became automatic: MCP tools and prompts, prompt-time Goal Capsule creation where hooks are supported, pre-edit Work Contract checks where hooks are supported, post-edit refresh, checkpoints, Patch Passport finish flow, and slash commands or skills installed for this agent host.
```

For stricter setup, paste the full prompt:
Expand Down Expand Up @@ -186,15 +201,16 @@ EDGEBASE_PREFLIGHT=off
| Target | Project file | User file | Behavior |
| --- | --- | --- | --- |
| Edgebase cache/artifacts | `.edgebase/index.sqlite3`, `.edgebase/graphs/latest.*` | none | Rebuildable local graph cache plus optional visual artifacts, ignored by git |
| Edgebase session state | `.edgebase/session/active-goal.json`, `.edgebase/passports/latest.*` | none | Active Work Contract, recorded checks, latest Patch Passport, ignored by git |
| Git ignore | `.git/info/exclude` | none | Locally ignores `.edgebase/` without changing committed ignore files |
| Agent instructions | `AGENTS.md` marker block | none | Tells agents to use Edgebase automatically for broad exploration/editing |
| Claude Code | `.mcp.json`, `.claude/settings.json`, `.claude/skills/edgebase*/SKILL.md`, `.claude/skills/goal/SKILL.md` | none by default | MCP server, automatic Goal Capsules, PreToolUse stale-capsule blocking, SessionStart/PostToolUse/PreCompact/SessionEnd hooks, `/edgebase`, `/edgebase-goal`, `/goal`, and `/edgebase-*` command skills |
| Codex | `.codex/config.toml`, `.codex/hooks.json`, `.agents/skills/edgebase*/SKILL.md`, `.agents/skills/goal/SKILL.md` | `~/.codex/config.toml` | MCP server entry, project hook config, project skills including `/edgebase-*`, AGENTS.md routing |
| Claude Code | `.mcp.json`, `.claude/settings.json`, `.claude/skills/edgebase*/SKILL.md`, `.claude/skills/goal/SKILL.md` | none by default | MCP server, automatic Goal Capsules, PreToolUse Work Contract warnings or strict denials, SessionStart/PostToolUse/PreCompact/SessionEnd hooks, `/edgebase`, `/edgebase-goal`, `/goal`, and `/edgebase-*` command skills |
| Codex | `.codex/config.toml`, `.codex/hooks.json`, `.agents/skills/edgebase*/SKILL.md`, `.agents/skills/goal/SKILL.md` | `~/.codex/config.toml`, `~/.codex/skills/edgebase*/SKILL.md`, `~/.codex/skills/goal/SKILL.md` | MCP server entry, project hook config, project/global skills including `/edgebase-*`, AGENTS.md routing |
| Cursor | `.cursor/mcp.json` | `~/.cursor/mcp.json` | MCP server entry |
| Gemini CLI | `.gemini/settings.json` | `~/.gemini/settings.json` | MCP server entry |
| OpenCode | `.opencode.json` | `~/.opencode.json` | Enabled local MCP server |
| Windsurf | none | `~/.codeium/windsurf/mcp_config.json` | Global MCP server entry |
| Git | `.git/hooks/post-commit` | none | Refreshes the index after commits |
| Git | `.git/hooks/post-commit`, `post-checkout`, `post-merge`, `post-rewrite` | none | Refreshes the index after commits, branch switches, merges, and rebases |

No Docker, cloud service, graph database, or API key is required.

Expand All @@ -204,8 +220,8 @@ Generated hook and MCP config use the Python interpreter that ran setup instead

Most users do not run Edgebase manually after setup. When an explicit action is useful, run slash commands inside Claude Code, Codex, or any client that exposes project skills or MCP prompts.

- Claude Code: `UserPromptSubmit` records and injects a Goal Capsule before planning. `PreToolUse` blocks Write/Edit/MultiEdit if no fresh capsule exists. `PostToolUse` refreshes the graph after edits. `PreCompact` saves a checkpoint, and `SessionEnd` saves a Patch Passport. Project skills install `/edgebase`, `/edgebase-goal`, `/goal`, and the `/edgebase-*` command set.
- Codex: setup writes MCP config, project `.codex/hooks.json`, `[features] hooks = true`, `.agents/skills/edgebase*`, `.agents/skills/goal`, and the `AGENTS.md` marker. Codex uses MCP plus project skills by default; when trusted hook support is active, the same preflight gate records capsules, blocks stale edits, refreshes after edits, checkpoints before compaction, and saves a Patch Passport on stop.
- Claude Code: `UserPromptSubmit` records `.edgebase/session/active-goal.json` and injects a Goal Capsule before planning. `PreToolUse` warns before stale or risky Write/Edit/MultiEdit calls; `edgebase setup --strict` can deny unsafe edits. `PostToolUse` refreshes the graph after edits. `PreCompact` saves a checkpoint, and `SessionEnd` saves a Patch Passport. Project skills install `/edgebase`, `/edgebase-goal`, `/goal`, and the `/edgebase-*` command set.
- Codex: setup writes MCP config, project `.codex/hooks.json`, `[features] hooks = true`, `.agents/skills/edgebase*`, `.agents/skills/goal`, global Codex skills when global scope is selected, and the `AGENTS.md` marker. Codex uses MCP plus skills by default; when trusted hook support is active, the same runtime records capsules, checks the Work Contract before edits, refreshes after edits, checkpoints before compaction, and saves a Patch Passport on stop.
- Cursor, Gemini CLI, OpenCode, and Windsurf: Edgebase installs MCP config and a marker-bounded `AGENTS.md` instruction telling agents to use `edgebase_context` or `edgebase_goal` automatically before broad code exploration or edits. Those MCP calls update `.edgebase/graphs/latest.*` and return the artifact paths.
- Any client: the MCP prompts named `edgebase`, `edgebase-goal`, `goal`, and the `/edgebase-*` aliases are available for clients that expose MCP prompts or slash-command-style prompt menus.

Expand All @@ -216,7 +232,9 @@ Useful explicit slash commands inside supported agent REPLs/apps:
/edgebase-goal "add passwordless login without breaking OAuth"
/edgebase-radius "src/auth/login.py" --goal "add passwordless login without breaking OAuth"
/edgebase-passport "add passwordless login without breaking OAuth" --test "python3 -m unittest -v: pass"
/edgebase-status
/edgebase-preflight-status
/edgebase-finish "add passwordless login without breaking OAuth" --test "python3 -m unittest -v: pass"
/edgebase-preflight-refresh "add passwordless login without breaking OAuth"
/edgebase-checkpoint "handoff after auth refactor"
/edgebase-resume
Expand All @@ -233,9 +251,11 @@ Shell fallback and server/development commands:
```bash
python3 -m edgebase install-prompt --agent codex
python3 -m edgebase context "change the auth login flow" --budget 1200
python3 -m edgebase goal "add passwordless login without breaking OAuth" --budget 1200
python3 -m edgebase goal "add passwordless login without breaking OAuth" --budget 1200 --record
python3 -m edgebase radius src/auth/login.py --goal "add passwordless login without breaking OAuth"
python3 -m edgebase passport "add passwordless login without breaking OAuth" --test "python3 -m unittest -v: pass"
python3 -m edgebase status
python3 -m edgebase finish "add passwordless login without breaking OAuth" --test "python3 -m unittest -v: pass"
python3 -m edgebase preflight status
python3 -m edgebase checkpoint "handoff after auth refactor"
python3 -m edgebase resume
Expand All @@ -260,8 +280,8 @@ Dynamic-language call graphs are confidence-scored. Low-confidence call edges ar

| Agent | Status | Notes |
| --- | --- | --- |
| Claude Code | Supported | Project `.mcp.json`; automatic UserPromptSubmit Goal Capsule; PreToolUse stale-capsule block; async PostToolUse refresh; PreCompact checkpoint; SessionEnd Patch Passport; `/edgebase`, `/edgebase-goal`, `/edgebase-radius`, `/goal`, and `/edgebase-*` project skills |
| Codex | Supported | Project `.codex/config.toml`, `.codex/hooks.json`, `.agents/skills`; global `~/.codex/config.toml` MCP entry for CLI discovery; verify with `codex mcp list` and `python3 -m edgebase doctor` |
| Claude Code | Supported | Project `.mcp.json`; automatic UserPromptSubmit Goal Capsule; warn-by-default PreToolUse Work Contract checks with optional strict denial; async PostToolUse refresh; PreCompact checkpoint; SessionEnd Patch Passport; `/edgebase`, `/edgebase-goal`, `/edgebase-radius`, `/goal`, and `/edgebase-*` project skills |
| Codex | Supported | Project `.codex/config.toml`, `.codex/hooks.json`, `.agents/skills`; global `~/.codex/config.toml` MCP entry and global skills for CLI discovery; verify with `codex mcp list` and `python3 -m edgebase doctor` |
| Cursor | Supported | Project and global `mcp.json`; Cursor says Composer Agent automatically uses relevant MCP tools |
| Gemini CLI | Supported | Project and global `settings.json` with `mcpServers` |
| OpenCode | Supported | Local MCP server under `mcp.edgebase`, `enabled: true` |
Expand All @@ -286,11 +306,11 @@ The cache is rebuildable. Git remains the source of truth.
Automation layers:

- prompt hook: Claude Code and trusted Codex hooks record a Goal Capsule before the agent starts planning
- pre-edit hook: Write/Edit/MultiEdit is blocked when no fresh Goal Capsule exists
- pre-edit hook: Write/Edit/MultiEdit receives Work Contract warnings by default; strict setup can deny missing/stale contracts or protected-path edits
- edit hook: edited files are reindexed and edit deltas are returned after Write/Edit/MultiEdit
- compaction hook: `.edgebase/checkpoints/latest.md` preserves the active capsule before context compaction
- session-end hook: `.edgebase/passports/latest.md` and `.json` preserve changed files and explicit evidence at stop/session end
- git hook: post-commit refresh keeps the cache aligned with committed changes
- git hook: post-commit, post-checkout, post-merge, and post-rewrite refresh keep the cache aligned with branch and history changes
- MCP: every supported agent gets `edgebase_context`, `edgebase_goal`, checkpoint, fork-plan, and resume tools over stdio
- graph artifacts: hooks and MCP calls refresh self-contained local HTML, JSON, and DOT files and surface their paths as optional visual aids
- AGENTS marker: static repo instructions stay tiny and tell agents to route structural context through Edgebase
Expand Down
Loading
Loading