| name | octocode-awareness |
| description | Use when coordinating work in a shared repo — multi-agent or solo across sessions: collision avoidance, handoffs, verification debt, durable memory/wiki, hooks setup/debug, and repo learning before planning, editing, reviewing, or testing. |
| hooks | {"PreToolUse":[{"matcher":"^(?:Write|Edit|MultiEdit|NotebookEdit)$","hooks":[{"type":"command","command":"${CLAUDE_SKILL_DIR}/scripts/hooks/pre-edit.sh","timeout":20}]}],"PostToolUse":[{"matcher":"^(?:Write|Edit|MultiEdit|NotebookEdit)$","hooks":[{"type":"command","command":"${CLAUDE_SKILL_DIR}/scripts/hooks/post-edit.sh","timeout":20}]}],"PostToolUseFailure":[{"matcher":"^(?:Write|Edit|MultiEdit|NotebookEdit)$","hooks":[{"type":"command","command":"${CLAUDE_SKILL_DIR}/scripts/hooks/post-edit.sh","timeout":20}]}],"SubagentStart":[{"hooks":[{"type":"command","command":"${CLAUDE_SKILL_DIR}/scripts/hooks/notify-deliver.sh","timeout":20}]}],"Stop":[{"hooks":[{"type":"command","command":"${CLAUDE_SKILL_DIR}/scripts/hooks/stop-verify.sh","timeout":20}]}],"SubagentStop":[{"hooks":[{"type":"command","command":"${CLAUDE_SKILL_DIR}/scripts/hooks/stop-verify.sh","timeout":20}]}],"PreCompact":[{"hooks":[{"type":"command","command":"${CLAUDE_SKILL_DIR}/scripts/hooks/session-compact.sh","timeout":20}]}],"SessionEnd":[{"hooks":[{"type":"command","command":"${CLAUDE_SKILL_DIR}/scripts/hooks/session-end.sh","timeout":20}]}],"UserPromptSubmit":[{"hooks":[{"type":"command","command":"${CLAUDE_SKILL_DIR}/scripts/hooks/notify-deliver.sh","timeout":20}]}]} |
Octocode Awareness
AGENTS routes; skill decides; CLI/SQLite acts; hooks automate deterministic edges. Memory and .octocode/ are leads. Never hand-edit .octocode/.
Run live-state actions through the CLI.
When the host supports delegation, ALWAYS batch routine deterministic Awareness CLI reads, writes, and maintenance into one phase.
Use the smallest capable low-cost agent (for example Haiku or Composer 2.5); supply decided scope, require --compact, and cap its receipt at 512 bytes.
The lead retains destructive approval, conflict handling, memory-truth judgment, and verification.
Run directly only when the host cannot delegate.
Lifecycle
<cli>: local node packages/octocode-awareness/out/octocode-awareness.js; installed npx @octocodeai/octocode-awareness. Set OCTOCODE_AGENT_ID per agent/session.
BEFORE/READ+REASON -> DURING/DO -> AFTER/VERIFY -> LEARN? -> CLEAN? -> PROJECT?
- BEFORE:
attend; follow next; state goal, acceptance, affected scope, and evidence. Use memory recall --smart only if it may change the plan; choose task or WORK.
- DURING: declare paths via hooks or
work start; read peers. Ordinary overlap is allowed; never bypass conflict. Hooks never choose plans, locks, success, learning, cleanup, or projection.
- AFTER: check while present;
task submit/work end; verify mark; verify audit. Expiry never means success.
- OPTIONAL:
reflect record --lesson only for verified reusable outcomes; clean only under pressure; project only for file readers.
Loop: attend -> work start -> edit/check -> work end -> verify mark -> verify audit; add --exclusive when required. lock wait/prune are recovery.
Feature map — all features; load owners only for depth
- Orient/state:
attend, workspace status, query, session capture, agent registry. When inspecting storage/session, load references/architecture.md for storage boundaries.
- Plan/task: dependencies/readiness/claim/heartbeat/submit/release. When choosing plan, task, or WORK, load
references/plan-task-workflow.md for task routing.
- Work/files:
start/touch/end/list/show. When overlap matters, load references/files-awareness.md for peer semantics.
- Exclusive work/verify:
work start --exclusive, lock recovery, mark/audit. When exclusivity or debt matters, load references/lock-protocol.md for conflict gates.
- Signals/refinements: signal publish/list/reply/ack/resolve/prune; refinement get/set/delete. When peers interact, load
references/coordination-protocol.md for peer flow.
- Memory: recall/record/forget/archive/restore; correct with
--supersedes. When using memory, load references/memory-recall.md for trust rules.
- Reflection/review: reflect/review/export harness. When improving, load
references/improve-loop.md for acceptance gates.
- Knowledge/wiki: docs/staleness,
wiki sync, projections. When choosing output, load references/output-routing.md for lean routing.
- Hooks/hosts: install/check/remove/run across Claude/Codex/Cursor/Pi. When configuring/debugging, load
references/hooks.md.
- Maintenance/contracts: maintenance and schema commands/list/path/json-schema/example/validate. When cleaning/learning, load
references/bookkeeping.md for pressure gates.
- Recipes: when a start, finish, or command recipe is unknown, load
references/agent-cheatsheet.md; unknown owner only: docs list --compact, then docs show <name>.
- Skill evolution: when shipping a skill change, load
references/skill-evolution.md; use octocode-eval for goal/KPI, octocode-research for evidence, and octocode-skills for review.
Scripts: use scripts/awareness.mjs for fallback, scripts/schema.mjs for contracts, scripts/hook-runner.mjs for events, scripts/extract-hook-files.mjs for paths, scripts/install.mjs --compact for diagnosis; run scripts/smoke-multi-agent.mjs when validating coordination.
Installation and first activation
Load README.md; initialize once, then attend. Claude uses frontmatter; do not install duplicate project hooks. When configuring Codex/Cursor, load references/hooks.md; Pi uses its bridge. Rebuild with yarn workspace @octocodeai/octocode-awareness build; never edit mirrors.
