Rocky

Release v0.7.6 | Changelog | License | Security | Contributing

Rocky is a blind engineer who lives in your terminal. He remembers failed commands and what fixed them, then brings that history back when the same trouble returns. Supported agent hooks can also keep a bounded record of what you asked for, which files changed, and why the agent said it changed them.

The useful part is local and deterministic. Rocky has no daemon, no telemetry, and zero runtime dependencies. Optional AI uses an Ollama instance that you run on loopback.

You teach, I remember. I remind, you understand. This is good trade.

Install

npm install -g @poggufanz/rocky-cli

Requires Node.js 18 or newer. The package name is @poggufanz/rocky-cli; the unrelated unscoped rocky-cli package is not this project.

Current release: @poggufanz/[email protected]. See the release notes or the full changelog.

Agent self-setup (any harness). Working with an agent outside Claude Code or Codex (OpenCode, Gemini CLI, anything else)? docs/agents/INSTALL.md covers the shell hook, the notify rationale lane, and optional MCP read access, and every step that edits your files asks for approval first. On Claude Code and Codex, rocky setup --agent-hooks and rocky setup capture more, automatically. To hand it to the agent:

Fetch and follow instructions from https://raw.githubusercontent.com/poggufanz/rocky/main/docs/agents/INSTALL.md

Quick start

Run a failure-prone command through Rocky:

rocky run "npm run build"

When it fails, Rocky fingerprints the useful stderr lines and writes a local record. When the same reliable command later succeeds in the same directory, Rocky links that success as the fix.

rocky recall "build failure"
rocky stats

On Bash, WSL, or PowerShell, install the shell hook if you want passive command memory:

rocky hook install

rocky setup and rocky hook install are separate on purpose. MCP or agent setup never edits .bashrc or $PROFILE.

On Windows, rocky hook install installs into every PowerShell host it finds on the machine — Windows PowerShell and PowerShell 7, both when present, each into its own $PROFILE — alongside the Bash hook if .bashrc is also in play (Git Bash/WSL). rocky hook status reports each host separately.

The PowerShell hook is passive ears only: it overrides prompt to see a command's result right after it finishes, so it remembers failures and links fixes the same way Bash does, but — unlike the Bash hook — it cannot ask for confirmation before a dangerous command runs, because prompt never sees a command before it executes. Because prompt fires after the command's own stderr is already gone, PowerShell-hook failures are fingerprinted from the command text alone, the same command-only fallback the CLI has used since v0.4.0. One disclosed side effect: the only way PowerShell allows restoring $? to False after Rocky's own bookkeeping runs is a real, suppressed non-terminating error, which pushes one synthetic entry — named so you know it is Rocky's — onto the front of $Error, ahead of whatever your last real command actually raised. $LASTEXITCODE and $?'s value are always exactly what your own command left them; only $Error[0]'s position shifts.

What ships

| Surface | What it does | | --- | --- | | Failure memory | Fingerprints errors, remembers later fixes, and searches your own history. | | rocky dash | Browse and inspect remembered failures, fixes, triples, and diffs in an interactive terminal dashboard. | | rocky watch | Waits with a long-running command, saves a failed stderr tail, and notifies when work ends. | | rocky check | Scans a pending push for secrets, checks new npm package names after consent, and asks one non-blocking comprehension question. | | Nervous System | Supported Claude Code and Codex hooks record bounded intent, path, excerpt, and stated-rationale evidence. | | Dictionary | what, how, why, digest, and quiz turn remembered changes back into plain explanations. | | Read-only MCP | Exposes bounded memory tools over local stdio, with sanitized output by default. | | Rationale gate | A concept lexicon (rocky concepts) plus a PreToolUse gate that nudges an editing agent to state why before it touches a file; deny-once, fail-open. |

Rocky preserves wrapped-command stdout, stderr, TTY behavior, and exit status. Persona lines go to stderr, so piped stdout stays clean.

Command map

| Command | Use | | --- | --- | | rocky run "<cmd>" | Run a command with deep failure memory. | | rocky dash [query] | Browse and inspect remembered failures, fixes, triples, and diffs in an interactive terminal dashboard. | | rocky watch "<cmd>" | Run a long command with completion notice and failure log. | | rocky brief [--since <ref\|24h>] [--quiet] [--ai] | Hear what changed since last brief: commits, remembered failures/fixes, touched invariant guards. Local git and memory only, no network; --ai stays on loopback. | | rocky recall [--ai] "<query>" | Search remembered failures and fixes. | | rocky stats | Show memory totals and coverage. | | rocky journal "<note>" | Write one line to your dogfood journal. Local file only, no network. | | rocky invariants | List remembered invariant notes and hear which globs guard nothing. | | rocky check | Inspect the commits or workspace about to be pushed. | | rocky hook install\|status\|uninstall | Manage the Bash/WSL hook, and on Windows every detected PowerShell host's hook. | | rocky what, rocky how [--diff], rocky why [--diff] [--add "<text>"] | Look up remembered intent/mechanism evidence, with optional correlated git diff, or teach your own rationale. | | rocky digest, rocky quiz, rocky export | Review or export recent learning records. | | rocky concepts, rocky concept <id>, rocky concept alias | List, look up, and teach concepts heard in memory. | | rocky sessions [n], rocky repl [--ai] | Browse derived work sessions, or stay in one loop over recall/what/why/how. | | rocky setup | Register detected MCP hosts after consent. | | rocky mcp | Start the local read-only stdio server. | | rocky model status\|use\|off | Configure optional loopback Ollama. | | rocky hook gate-event, rocky hook agent-event generic | PreToolUse rationale-gate enforcement and the universal agent notify endpoint. |

Setup stays explicit:

rocky setup
rocky setup --voice-skill
rocky setup --agent-hooks
rocky setup --uninstall-agent-hooks
rocky setup --status

For optional local ranking, install and manage Ollama yourself, then opt in:

rocky model use qwen3:0.6b-q4_K_M
rocky recall --ai "sharp build failure"
rocky model off

Rocky never installs or pulls a model, and it does not start or stop the shared Ollama daemon.

Rationale evidence and the gate

Stated-rationale evidence arrives through four lanes, ranked by fidelity:

| Lane | Source | Fidelity | | --- | --- | --- | | log-thinking | Claude Code or DSH session logs, when a thinking block exists | raw | | log-response | Claude Code session logs' response text, when no thinking block exists | summary | | notify | Any agent calling rocky hook agent-event <adapter> --rationale "<text>" | summary | | human | You, via rocky why --add "<text>" | summary |

An unlinked file has no rationale evidence yet; that is a first-class honest state, not a gap Rocky papers over. The DSH log adapter needs Node 22.15 or newer at runtime for built-in zstd support — on an older Node it feature-detects the gap, skips DSH logs, and discloses that instead of guessing. rocky setup --agent-hooks installs a PreToolUse rationale gate by default (rocky hook gate-event claude-code): it denies once per session per file when no rationale evidence exists yet, then fails open for that file every time after. Opt out at install with --no-rationale-gate, or at runtime with ROCKY_RATIONALE_GATE=off. Codex and other non-Claude-Code agents have no deny hook at all; they reach the notify lane only.

Privacy and local state

Persistent state lives under ROCKY_HOME; the default is ~/.rocky. The main record is append-only JSONL at memory.jsonl. Depending on the features you use, that directory can also hold config, watch logs, a transient agent spool, labels, and guard rules.

Memory can contain commands, errors, working directories, prompts, bounded file excerpts, and an agent's stated rationale. Treat it as developer history: read it, back it up, or delete it on your terms.

The CLI contains no telemetry and runs no daemon. Its only external network egress is rocky check asking registry.npmjs.org whether a newly added package name exists. The lookup is consent-gated, sends package names only, and is fail-open when offline. Everything else stays local; optional AI connects only to 127.0.0.1. MCP projects sanitized memory by default, and raw exposure is an explicit opt-in. A configured cloud host may forward selected projected content under that host's own policy.

Read the security policy before enabling raw MCP exposure or installing hooks into a shell or agent host.

Documentation

• Behavior and safety reference covers command boundaries, memory linking, setup transactions, MCP, and platform limits.
• Scientific grounding separates product hypotheses from measured research.
• Security policy explains private reporting, supported versions, sensitive state, and recovery artifacts.
• Contributing guide covers the development workflow and load-bearing code.
• Changelog and GitHub releases track shipped changes.

For questions and reproducible bugs, use GitHub Issues. Report exploitable findings through a private security advisory.

Development

git clone https://github.com/poggufanz/rocky.git
cd rocky
npm install
npm test

Repository layout: a fresh clone of the canonical upstream repository (https://github.com/poggufanz/rocky.git) is the package root; run npm install, npm test, and npm pack there. In this outer workspace, that same package root is the rocky/ directory. Canonical developer branch is main; iq is a remediation branch, not a second release line.

Read the contributing guide before changing setup, MCP, file transactions, or shell hooks. Those paths refuse uncertain state rather than guessing. The full npm test run is the release gate.

Roadmap

• v0.2.1 - distribution bridge (historical): scoped npm package, Bash/WSL hook, read-only MCP, host setup, and optional local AI.
• v0.3 - his patience (implemented): rocky watch for long-running work.
• v0.4 - his diligence (implemented): rocky check before a push.
• v0.5 - his curiosity (implemented): Nervous System hooks, intent-mechanism dictionary, teaching commands, and bounded MCP knowledge tools.
• v0.6 - his accountability (implemented): rocky brief, rocky journal, rocky invariants, extended rocky stats, and the schema envelope documentation.
• v0.7 - his memory of why (current release): stated-rationale evidence across four lanes, a concept lexicon (rocky concepts), derived rocky sessions and rocky repl, and the PreToolUse rationale gate.

BYOK annotation, attest, and the memory circuit breaker remain deferred. Codex and Gemini agent-log adapters are deferred too — Codex's local session format drifted to a SQLite hybrid, and Gemini persists no thoughts to read. The earlier rocky explain idea is superseded and is not an active command.

License and attribution

Rocky CLI code, original project documentation, and the repository illustration are available under the MIT License.

Rocky's character, voice, and illustration are original work created for this repository. No third-party logos, film assets, or other copyrighted material are distributed here.