eforge 1.0.7

Codebase observation graph and mapping tools

eforge

Codebase observation graph for developers. Map your codebase. Track concepts. Find relationships.

Install

pip install eforge

That installs three packages only: eforge, click, and PyYAML.

Install	What you get
pip install eforge	Standalone CLI: init, task, node, schema, error
Monorepo checkout	Adds runtime commands: orient, search, declare, inspect, … via ActionRegistry
pip install eforge[compiler]	Reserved for a future full graph runtime on PyPI (not published yet)

Project bootstrap

Two storage domains — do not conflate them:

Domain	Directory	Created by
eforge (observation)	.eforge/schemas/, .eforge/observations/	eforge init
Declaration (manifest graph)	.forge/manifest.yaml, .forge/tasks/	eforge declare, eforge console, or legacy forge init

cd your-project
eforge init                    # .eforge/ only
eforge node add "Auth" -y      # observation graph
eforge task add --title "..." -y   # creates .forge/tasks/ on first use

# With compiler runtime (monorepo):
eforge declare -y                # bootstraps .forge/ if needed
eforge console

Legacy repos may still have observations under .eforge/observations/; new projects use that path. Older .forge/observations/ layouts are read as fallback.

No setup needed

After eforge init, add nodes anytime:

eforge node add "AuthSystem" --kind concept/feature -y
eforge node add "auth.py" --kind core/file \
  --file src/auth.py -y
eforge node link "AuthSystem" "auth.py" \
  --rel housed-in \
  --note "core auth logic" -y
eforge node show "AuthSystem"

Commands

eforge node     add, show, list, find, link,
                note, tag, mark, edit, inspect
eforge schema   list, show, create, edit,
                validate, copy, restore
eforge error    lookup (<CODE>), --list, --search, --stats

Your own schemas

eforge ships with built-in schemas for common node types. Add project-specific schemas without touching forge:

eforge schema create game/canvas

This creates .eforge/schemas/domain/game/canvas.yaml. Your schema is immediately available:

eforge node add "PixelCanvas" --kind game/canvas
# SchemaPrompt uses YOUR schema properties

Schema search order:

1. .eforge/schemas/ (your project)
2. forge built-ins

Built-in kinds: concept/feature, core/file, ui/screen, ui/variant, ui/component, architecture/session, architecture/boundary, data/model, data/table, data/rpc, code/class, code/function, code/module

Node types

concept/feature planned features, systems, capabilities
core/file       source files

Relationship types

housed-in       concept → file
relates-to      concept → concept
depends-on      A needs B
implements      code implements concept
raises          code raises error

Storage

.eforge/schemas/              project type schemas
.eforge/observations/
  nodes/                      one yaml per node
  .cache/                     SQLite index (auto-rebuilt)
.forge/manifest.yaml          declaration graph (not created by eforge init)
.forge/tasks/                 work items (created on first task add)

No AI required

Works without any AI assistant. Map your codebase manually, one node at a time.