orientation

orientation

orientation reconstructs the real history of code from Codex, Claude Code, and Eigen transcripts and exposes it through the get-oriented skill, so an agent does not have to guess why unfamiliar code exists.

It answers the questions that matter before a cleanup, bug call, or nearby change:

• What human goal created or changed this file?
• Was the work committed, failed, paused, or still in flight?
• How recently was it touched relative to the rest of the project?
• Which files usually moved with it?

The engine is plain Node.js, has no runtime dependencies, and does not call a model or external service. It derives structural signal from local transcript JSONL: prompts, tool calls, edits, tests, commits, and file co-edits.

Status

This repository is ready for public GitHub use and local installation from GitHub. The package name is reserved in package.json as @agent-sh/orientation, but it is not published to npm yet.

orientation installs two ways from one repo:

• Claude Code marketplace plugin - /plugin install copies the bundled engine, the get-oriented skill, and declarative SessionStart/Stop/PreCompact hooks. State is written to the plugin's data dir; no npm step runs.
• npm package - npm i -g runs install.js, which copies the engine + skill and wires hooks for Claude Code (settings.json), Codex (harness-owned contract printed), and Eigen (hooks.json).

Current host support:

• Claude Code: marketplace plugin OR installer; copies the engine, installs the skill, wires SessionStart, Stop, and PreCompact hooks.
• Codex: installer copies the engine and skill; Codex hooks are harness-owned, so the installer prints the hook contract to wire into your harness instead of editing config.
• Eigen: installer copies the engine and skill and wires the turn_done, session_stop, and note hooks in hooks.json.

Install (Claude Code marketplace)

The simplest path for Claude Code - no npm, no postinstall:

/plugin marketplace add agent-sh/agentsys
/plugin install orientation@agentsys

The plugin bundles the engine under src/, the skill under skills/get-oriented/, and hooks/hooks.json. Hooks run the bundled engine with ORIENTATION_ENGINE_DIR=${CLAUDE_PLUGIN_ROOT}/src and write graph data to the plugin's persistent data dir (${CLAUDE_PLUGIN_DATA}), so nothing touches ~/.claude/action-graph. With an empty allowlist it indexes every project; add prefixes to projects.txt in the data dir to scope it.

Install (npm)

Install directly from GitHub:

npm install -g github:agent-sh/orientation

Or from a local clone:

git clone https://github.com/agent-sh/orientation.git
cd orientation
npm install -g .

The installer is idempotent. It can be re-run safely, and you can target one runtime or all:

orientation sync            # all runtimes (codex + claude + eigen)
orientation sync --claude   # Claude Code only
orientation sync --codex    # Codex only
orientation sync --eigen    # Eigen only

By default it writes to:

• ~/.claude/action-graph/ for the Claude engine and graph data, plus ~/.claude/skills/get-oriented/SKILL.md and hooks in ~/.claude/settings.json.
• ~/.eigen/orientation/ for the Codex/Eigen engine and graph data, plus skills under ~/.codex/skills/get-oriented/ and ~/.eigen/skills/get-oriented/ and Eigen hooks in ~/.eigen/hooks.json.

Quick Start

Opt projects into transcript indexing by adding one cwd prefix per line to the engine home's projects.txt (~/.claude/action-graph/projects.txt for Claude, ~/.eigen/orientation/projects.txt for Codex/Eigen):

echo "$HOME/projects" >> ~/.claude/action-graph/projects.txt

Build the graph:

orientation refresh

Ask for provenance before judging a file:

orientation provenance "$PWD" src/example.js

Ask for related prior work before adding near a file:

orientation related "$PWD" src/example.js

If there are no transcripts for the project yet, orientation will say so. That is a useful result: no recorded provenance is not evidence that code is dead.

What The Skill Does

The installed get-oriented skill tells an agent to check orientation before it:

• answers "what is the state here?" or "what is next?"
• judges unfamiliar code as broken, stale, dead, or trustworthy
• deletes or guts code whose purpose is being inferred
• adds behavior near existing code it did not write in the current un-compacted session

The key rule is recency-first: