Jerry Framework Installation Guide¶
Your AI coding partner just got guardrails, knowledge accrual, and a whole crew of specialized agents. Let's get you set up and shredding.
Platform Note: Jerry is built and battle-tested on macOS. Linux works — CI runs Ubuntu on every job and the tooling is cross-platform. Windows support is in progress — skills and core functionality work, but hooks that use symlinks or path-sensitive operations may behave differently. Known Windows limitations: bootstrap uses junction points instead of symlinks, and paths in Claude Code commands must use forward slashes. See Platform Support for details. Hit a wall? File it via the Windows compatibility template.
Document Sections¶
| Section | Purpose |
|---|---|
| Prerequisites | What you need before dropping in |
| Which Install Method? | Four paths, one Jerry — pick the line that fits your setup |
| Install from GitHub | Persistent install via Claude Code's plugin system (~2 min) |
| Enable Hooks | Session context and quality enforcement (early access — hooks may fail silently) |
| Capability Matrix | What works with and without uv |
| Local Clone | For offline use, version pinning, or locked-down networks |
| Session Install | Session-only install — skills available immediately, no configuration |
| Configuration | Project setup — required for skills to work |
| Verification | Confirm everything landed |
| Using Jerry | Getting started with skills |
| Developer Setup | Contributing to Jerry's codebase |
| Troubleshooting | When things don't land clean — common fixes |
| Updating | Pull latest changes — GitHub users vs local clone |
| Uninstallation | Clean removal: plugin, source, and local files |
| Getting Help | Support and docs |
| License | Apache 2.0 — use freely, attribution required |
First time here? Start with Which Install Method? to pick the right path in under a minute.
Prerequisites¶
| Software | Required? | Purpose |
|---|---|---|
| Claude Code 1.0.33+ | Yes | The AI coding assistant Jerry extends |
| SSH key configured for GitHub | No — HTTPS alternative available | The owner/repo shorthand clones via SSH; HTTPS URL works without SSH |
| uv | Recommended | Enables hooks (session context, quality enforcement) |
Network access: The GitHub install method needs outbound access to
github.com(andraw.githubusercontent.comfor plugin discovery). If you install uv for hooks, the installer reachesastral.sh. The Local Clone method requiresgithub.comonly for the initial clone — after that, no network access is needed. For fully air-gapped environments, see Air-gapped install under Local Clone.Why does SSH come up? When you add a plugin source using the
owner/reposhorthand (e.g.,geekatron/jerry), Claude Code clones the repository via SSH. Even though Jerry's repo is public, theowner/repoformat defaults to SSH. If you don't have SSH keys configured for GitHub, you'll see "Permission denied (publickey)." The fix is simple: use the full HTTPS URL instead. Both commands do the same thing. See Install from GitHub for both options side by side.Don't have Claude Code yet? No worries — install it first via Anthropic's Claude Code quickstart. Takes a few minutes. We'll be here when you get back.
Version check: The
/plugincommand requires Claude Code 1.0.33+. Runclaude --versionto check. If/pluginis not recognized, update Claude Code first.
Which Install Method?¶
Four install methods — all get you the same Jerry. Pick the line that fits your setup.
| Your Situation | Method | Time |
|---|---|---|
| Internet access + SSH key configured for GitHub | Install from GitHub (SSH) | ~2 minutes |
| Internet access, no SSH key — or you're not sure | Install from GitHub (HTTPS) | ~2 minutes |
| Offline or network-restricted — corporate firewall, air-gapped, or version-pinned | Local Clone | ~5 minutes |
| Session-only install — skills available immediately, no configuration needed | Session Install | ~3 minutes |
Not sure if you have SSH configured? Run
ssh -T git@github.comin your terminal. If you seeHi <username>!and<username>is your GitHub account, you have SSH set up. If the username is unexpected, or you see "Permission denied," use the HTTPS path — same result, same speed, no SSH needed.
Not sure which to pick? Start with Install from GitHub using the HTTPS URL. It works for everyone.
Install from GitHub¶
Jerry is a community Claude Code plugin hosted on GitHub. It is not part of the official Anthropic plugin catalog — you install it directly from the GitHub repository using Claude Code's built-in plugin system.
What does "marketplace" mean here? Claude Code uses the word "marketplace" in its
/plugin marketplacecommands, but for community plugins like Jerry, it just means "register a plugin source." Any GitHub repository with a.claude-plugin/marketplace.jsonfile can serve as a plugin source. Jerry's GitHub repository is its own marketplace. This is separate from the official Anthropic marketplace, which is automatically available in Claude Code and contains Anthropic-curated plugins.Where do I type these commands? All
/plugincommands are typed into Claude Code's chat input — the same text box where you send messages to the AI. Type the command and press Enter. These are not terminal commands.Arriving from the HTTPS row in the table above? Use the HTTPS command in Step 1 below (the second row in the table). It works without SSH keys.
Step 1: Add the Jerry repository as a plugin source
Pick whichever command matches your setup — all three do the same thing:
| Your Setup | Command |
|---|---|
| SSH key configured (shorthand) | /plugin marketplace add geekatron/jerry |
| SSH key configured (explicit URL) | /plugin marketplace add git@github.com:geekatron/jerry.git |
| No SSH key (or not sure) | /plugin marketplace add https://github.com/geekatron/jerry.git |
The
owner/reposhorthand resolves to SSH under the hood — it's equivalent to the explicit SSH URL. Both require an SSH key configured for GitHub. The HTTPS URL works without SSH keys.
This tells Claude Code where to find Jerry. Nothing is installed yet — you're just registering the source.
SSH authentication failed? If you see "Permission denied (publickey)", use the HTTPS command from the table above. It clones over HTTPS — no SSH keys needed.
Step 2: Verify the source registered
Run this to confirm Jerry's marketplace source was added:
You should see jerry-framework in the output. This is the source name you'll use in the next step. If you don't see it, re-run Step 1.
Shortcut: You can also type
/plugin market list— Claude Code acceptsmarketas shorthand formarketplace.
Step 3: Install the plugin
Use the source name from Step 2's output as the @suffix:
If Step 2 showed jerry-framework (the default), the command is:
This downloads and activates Jerry's skills, agents, and hooks. The format is plugin-name@source-name — jerry is the plugin name and the part after @ is the source name you verified in Step 2.
"Plugin not found"? The source name must match exactly what
/plugin marketplace listshows. Re-run Step 2 and copy the name from the output. The source name comes from Jerry's.claude-plugin/marketplace.json— you can inspect it to verify.
Step 4: Confirm it landed
- Run
/pluginin Claude Code - Go to the Installed tab
- Verify
jerryappears in the list
If jerry appears, you're in. Head to Configuration to set up your first project, then Verification to confirm everything's firing.
Installation Scope¶
During install, Claude Code asks which scope to use:
| Scope | Effect | When to Use |
|---|---|---|
| User (default) | Installs for you across all projects | Personal use — this is what most people want |
| Project | Added to .claude/settings.json (version-controlled) |
Team-wide — everyone who clones the repo gets Jerry |
| Local | Only you, only this repository | Testing a specific version |
Recommendation: Use User for personal use. Use Project when you want your whole team using Jerry — the settings file is committed to version control, so new team members get Jerry the moment they clone.
Interactive Installation (after adding the source)¶
Important: Jerry won't appear in the Discover tab until you complete Step 1 above (adding the plugin source via CLI). The Discover tab shows plugins from all registered marketplaces — Jerry is a community plugin, not part of the official Anthropic catalog, so it only appears after you add its source.
After completing Step 1, you can also install through the /plugin UI:
- Run
/plugin - Navigate to the Discover tab — Jerry will appear here because you registered its source
- Find
jerryand press Enter - Select your installation scope
Something not working? If the GitHub path gives you trouble, the Local Clone method always works. Then file an issue so we can smooth the primary path.
Enable Hooks (Early Access)¶
Early access caveat: Hook enforcement is under active development. Some hooks may have schema validation issues that cause them to fail silently (fail-open behavior — skills always work, but enforcement may not fire). The most stable hooks are SessionStart and UserPromptSubmit. PreToolUse and SubagentStop may experience schema issues in some Claude Code versions. After installing uv: 1. Start a new Claude Code session and check whether the
<project-context>tag appears (SessionStart hook) 2. If the tag is absent, check the/pluginErrors tab and GitHub Issues taggedhooksfor known issues
Skills work the moment you install. Hooks are the next level — they're what keep Jerry dialed across your entire session: auto-loading context at startup, reinforcing quality rules every prompt, catching state before compaction wipes it, and keeping the agent hierarchy honest. Think of hooks as Jerry's immune system — the skills are the muscles, but hooks keep everything running clean underneath.
They need uv. It takes 30 seconds.
What hooks give you¶
| Hook | What It Does |
|---|---|
| SessionStart | Auto-loads project context, rules, and quality framework at session start |
| UserPromptSubmit | Re-injects critical rules every prompt to combat context rot (L2 enforcement) |
| PreCompact | Saves critical context before compaction — Jerry's defense against losing state when the context window fills |
| PreToolUse | AST-based validation and security guardrails before tool calls execute (L3 enforcement) |
| SubagentStop | Enforces single-level subagent hierarchy and captures orchestration handoffs (P-003) |
| Stop | Context stop gate — preserves session state on exit |
Install uv¶
Security note: The commands below download and execute a script from
astral.sh. This is a standard pattern for developer tools (Rust, Homebrew, and others use it). If your organization requires script inspection before execution: on macOS/Linux, download first withcurl -LsSf https://astral.sh/uv/install.sh -o install-uv.sh, review it, then runsh install-uv.sh; on Windows, download first withInvoke-WebRequest https://astral.sh/uv/install.ps1 -OutFile install-uv.ps1, review it, then run.\install-uv.ps1. Alternatively, install via pip or your system package manager.
macOS / Linux:
Windows (PowerShell):
After installing, restart your terminal (close and reopen), then verify:
Once uv is installed, hooks should activate automatically the next time you start Claude Code. Quick check: start a new session — if you see a <project-context> tag in the output, hooks are live. For the full checklist, see Hooks verification below.
Note: You do NOT need Python installed separately. uv handles Python automatically.
Capability Matrix¶
| Feature | Without uv | With uv |
|---|---|---|
| All 12 skills (see Available Skills) | Yes | Yes |
| Session context auto-loading | No | Yes |
| Per-prompt quality reinforcement (L2) | No | Yes |
| Pre-compaction context protection | No | Yes |
| Pre-tool-use guardrails (L3, fail-open — see early access caveat) | No | Yes |
| Subagent hierarchy enforcement | No | Yes |
| Session state preservation on exit | No | Yes |
Without uv, you get the skills but not the guardrails. Everything still works — but the enforcement architecture that keeps Jerry honest across long sessions stays dark. Install uv. It's worth the 30 seconds.
Local Clone¶
Same Jerry, different delivery route. Use this method if you:
- Are in a network-restricted environment that blocks Claude Code's GitHub access
- Want offline access to Jerry's source
- Need to pin a specific version (e.g.,
git clone --branch v0.21.0) - Want to inspect the code before installing
Step 1: Clone the repository¶
macOS / Linux:
Windows (PowerShell):
New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\plugins"
git clone https://github.com/geekatron/jerry.git "$env:USERPROFILE\plugins\jerry"
Important: The clone path must not contain spaces. Claude Code's
/plugin marketplace addcommand does not support paths with spaces.
Step 2: Add as a local plugin source¶
In Claude Code (all /plugin commands are typed into Claude Code's chat input, not your terminal):
Windows (Claude Code): Use forward slashes — /plugin marketplace add C:/Users/YOUR_USERNAME/plugins/jerry
Replace YOUR_USERNAME with your actual Windows username. To find the full path, run echo $env:USERPROFILE in PowerShell.
Step 3: Verify and install¶
Run /plugin marketplace list to confirm the source registered, then install using the name from the list:
If the list showed jerry-framework (the default), the command is /plugin install jerry@jerry-framework.
"Plugin not found"? The source name must match exactly what
/plugin marketplace listshows. See Plugin not found in Troubleshooting.
Advanced: SSH clone¶
If you prefer SSH (e.g., you already have an SSH key configured with GitHub):
All subsequent steps are the same. See GitHub's SSH documentation for key setup.
Air-gapped install¶
For fully air-gapped environments where github.com is blocked entirely:
- Clone the repository from a machine with GitHub access
- Transfer the
jerry/directory to the restricted machine via your organization's approved file transfer method - Proceed from Step 2: Add as a local plugin source using the local path
uv in air-gapped environments: The uv installer also requires network access (to
astral.sh). For air-gapped uv installation, download a release binary from uv GitHub releases and place it in~/.local/bin/manually.
Version pinning¶
To pin Jerry to a specific release:
See releases for available tags.
Session Install (Plugin Dir Flag)¶
Want to try Jerry without any configuration? Clone the repo and point Claude Code at it directly — skills are available immediately, no plugin source setup needed:
# Clone if you haven't already
git clone https://github.com/geekatron/jerry.git ~/plugins/jerry
# Start Claude Code with Jerry loaded
claude --plugin-dir ~/plugins/jerry
Skills are available immediately — no /plugin install needed. Try /problem-solving in Claude Code's chat input to see what you're working with.
Note: The
--plugin-dirflag loads the plugin for that session only. It does not persist across sessions. For persistent installation, use the Install from GitHub or Local Clone methods. For users who launch Claude Code from a consistent project directory, session-scoped loading can be a legitimate workflow — not just a trial run.
Configuration¶
Project Setup (Required for Skills)¶
This is where Jerry goes from installed to yours. Jerry organizes your work into projects — each one is a workspace where your research, decisions, and work items build up over time. It's how Jerry remembers what you're working on across sessions, even when the context window resets.
Most skills need an active project to operate. Without one, you'll see <project-required> messages instead of skill output. Four steps and you're set.
- Navigate to your repository (the one where you want Jerry to work):
- Set the project environment variable:
# macOS/Linux
export JERRY_PROJECT=PROJ-001-my-project
# Windows PowerShell
$env:JERRY_PROJECT = "PROJ-001-my-project"
Project naming: The format is
PROJ-{NNN}-{slug}and it matters — Jerry's CLI and hooks validate this pattern. If you use a different format (e.g.,my-projectinstead ofPROJ-001-my-project), you'll see<project-error>messages. Pick any slug that describes your work (e.g.,PROJ-001-my-api). Your first project is typicallyPROJ-001.
- Make it persistent (so you don't lose it when you close the terminal):
# macOS/Linux — add to your shell profile
echo 'export JERRY_PROJECT=PROJ-001-my-project' >> ~/.zshrc
# Or ~/.bashrc if you use bash
# Windows PowerShell — create profile if needed, then add
if (!(Test-Path $PROFILE)) { New-Item -Path $PROFILE -Force }
Add-Content $PROFILE '$env:JERRY_PROJECT = "PROJ-001-my-project"'
Verify it stuck: Open a new terminal (to load the updated profile), then run
echo $JERRY_PROJECT(macOS/Linux) orecho $env:JERRY_PROJECT(Windows). If this prints your project ID, you're set. If it's empty, check that you saved the profile file and are using the correct shell.Launch order matters: Claude Code inherits environment variables from the terminal it was launched from. Set
JERRY_PROJECTfirst, then launch Claude Code. If Claude Code is already running, restart it from a terminal where the variable is set.
- Create project structure (run this from your repository root):
# macOS/Linux
mkdir -p projects/PROJ-001-my-project/.jerry/data/items
# Windows PowerShell
New-Item -ItemType Directory -Force -Path "projects\PROJ-001-my-project\.jerry\data\items"
Don't have a repository yet? Jerry works in any directory. Create one:
mkdir my-project && cd my-project && git init, then run themkdircommand above. Jerry doesn't require an existing codebase.The
.jerry/directory contains operational state and is gitignored — do not commit it. If you don't have a.gitignoreyet:echo '.jerry/' >> .gitignore. Jerry auto-creates additional subdirectories (work/,decisions/,orchestration/) as skills produce output. You only need the base structure above.
The SessionStart hook auto-loads project context when you start Claude Code. If you skip this section, skills will prompt you to set up a project when you invoke them — you'll know because you'll see <project-required> in the output.
Verification¶
Plugin verification¶
- In Claude Code, run
/plugin - Go to the Installed tab
- Verify
jerryappears in the list
Hooks verification¶
If you installed uv and set JERRY_PROJECT, start a new Claude Code session. The SessionStart hook fires automatically — you should see a <project-context> tag in the session output with your project name and loaded rules. If you see the tag, hooks are working — the SessionStart hook loaded your project context and quality rules. You're live.
No
<project-context>tag? Check the early access caveat. Hooks may have failed silently. Look at the/pluginErrors tab for details.
Skill test¶
You should see the problem-solving skill activate — it'll describe itself and list its available agents (researcher, analyst, architect, and the rest of the crew). That's the whole crew reporting for duty. You're live.
Seeing
<project-required>? This is the most common post-install issue — Jerry installed fine, but no project is configured. Go to Configuration and setJERRY_PROJECT. Make sure you ran themkdircommand from your repository root, not your home directory.
Check for errors¶
- Run
/plugin - Go to the Errors tab
- Verify no errors related to
jerry
Using Jerry¶
New to Jerry? Start by trying
/problem-solvingon a question you're working on, or/worktrackerto set up your first work items. Each skill guides you through what it needs. Let it rip.
Available Skills¶
| Skill | Command | Purpose |
|---|---|---|
| Problem-Solving | /problem-solving |
Research, analysis, architecture decisions |
| Work Tracker | /worktracker |
Task and work item management |
| NASA SE | /nasa-se |
Systems engineering processes (NPR 7123.1D) |
| Orchestration | /orchestration |
Multi-phase workflow coordination |
| Architecture | /architecture |
Design decisions and ADRs |
| Transcript | /transcript |
Meeting transcript parsing |
| Adversary | /adversary |
Adversarial quality reviews and tournament scoring |
| Eng Team | /eng-team |
Secure software engineering methodology |
| Red Team | /red-team |
Offensive security testing methodology |
| Saucer Boy | /saucer-boy |
McConkey personality for work sessions |
| AST | /ast |
Markdown AST operations (parse, query, validate) |
| Saucer Boy Framework Voice | /saucer-boy-framework-voice |
Internal: framework output voice quality gate |
Persistent Artifacts¶
Skill outputs are persisted to your project's work directory and docs directory, building your knowledge base over time:
| Output Type | Location |
|---|---|
| Work decomposition | projects/{JERRY_PROJECT}/work/ |
| Decisions (ADRs) | projects/{JERRY_PROJECT}/decisions/ or docs/design/ |
| Research, analysis, reviews | projects/{JERRY_PROJECT}/ subdirectories |
| Orchestration artifacts | projects/{JERRY_PROJECT}/orchestration/ |
These files survive context compaction and session boundaries. That's Jerry's core value — your work persists even when the context window doesn't.
Developer Setup¶
This section is for contributors to the Jerry codebase. If you installed Jerry as a plugin, you're done — go build something great.
See CONTRIBUTING.md for full development setup, coding standards, and platform-specific notes.
Quick start:
macOS / Linux:
git clone https://github.com/geekatron/jerry.git
cd jerry
make setup # Installs deps + pre-commit hooks
make test # Run test suite
Windows:
git clone https://github.com/geekatron/jerry.git
cd jerry
uv sync # Install dependencies
uv run pre-commit install # Install pre-commit hooks
uv run pytest --tb=short -q # Run test suite
Troubleshooting¶
Installation has a few rough edges — most of them are SSH or project configuration. Here's how to get through the common ones. If something isn't covered here, file an issue and we'll add it.
Project Issues¶
<project-required> or <project-error>
This is the most common post-install issue. It means Jerry installed successfully but no project is configured — the skills need somewhere to write their output.
Cause: JERRY_PROJECT is not set, points to a non-existent project, or the project directory was created in the wrong location.
Fix:
- Set the variable:
export JERRY_PROJECT=PROJ-001-my-project(macOS/Linux) or$env:JERRY_PROJECT = "PROJ-001-my-project"(Windows) - Verify the directory exists relative to your repo root:
ls projects/$JERRY_PROJECT/ - If the directory exists but in the wrong place (e.g., your home directory), move it under your repo's
projects/folder - If you haven't created a project yet, follow the Configuration section — it takes two minutes
SSH Authentication Issues¶
"Permission denied (publickey)" when adding plugin source
This is the second most common issue. The owner/repo shorthand uses SSH by default, which needs an SSH key configured for GitHub.
Fix (pick one):
-
Use the HTTPS URL (fastest fix — no SSH needed):
-
Set up SSH keys (if you use GitHub regularly):
- Follow GitHub's SSH key guide
-
After setup, retry:
/plugin marketplace add geekatron/jerry -
Configure Git to rewrite SSH to HTTPS globally (fixes it for all Git operations):
Then retry the original command. -
Use the Local Clone method — clone with HTTPS yourself, then point Claude Code at the local directory.
Plugin Install Issues¶
/plugin command not recognized
Plugins require Claude Code 1.0.33 or later. Check and update:
- Check your version:
claude --version - Update Claude Code:
- Homebrew:
brew upgrade claude-code - npm:
npm update -g @anthropic-ai/claude-code - Native installer: Re-run the install from Claude Code setup
- Restart Claude Code after updating
Plugin source add fails (non-SSH error)
If you're seeing an error that isn't about SSH authentication, check these:
- Internet connection — the command needs to reach GitHub
- Claude Code version — must be 1.0.33+
- Corporate proxy/firewall — if your network restricts GitHub access, use the Local Clone method instead
Plugin not found after adding source¶
If /plugin install jerry@jerry-framework returns "plugin not found," the source name doesn't match what Claude Code registered. If you followed Step 2 and already ran /plugin marketplace list, use the name you saw there. Otherwise:
- Run
/plugin marketplace listto see the actual source name - Use that name:
/plugin install jerry@<actual-name-from-list> - If the source doesn't appear at all, try removing and re-adding:
/plugin marketplace remove jerry-frameworkthen re-run the add command
The source name comes from Jerry's .claude-plugin/marketplace.json and should be jerry-framework, but it may register differently depending on how the source was added.
Hook Issues¶
uv: command not found
uv isn't on your PATH yet. Install it or fix the path:
macOS/Linux:
Windows:
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
# Close and reopen PowerShell
If still not found after restarting your terminal, add to PATH manually:
- macOS/Linux: export PATH="$HOME/.local/bin:$PATH" (add to ~/.zshrc or ~/.bashrc)
- Windows: Add %USERPROFILE%\.local\bin to System PATH
Hooks not firing
Hooks are in early access — some may fail silently. Here's how to diagnose:
- Verify uv is installed:
uv --version - Restart Claude Code completely (close and reopen)
- Check
/pluginErrors tab for any issues related to hooks - See the early access caveat for which hooks are most stable
Skill Issues¶
Skills not appearing
- Check
/pluginErrors tab for error indicators - Clear the plugin cache:
- macOS/Linux:
rm -rf ~/.claude/plugins/cache - Windows:
Remove-Item -Recurse -Force "$env:USERPROFILE\.claude\plugins\cache" - Restart Claude Code
- Reinstall:
/plugin uninstall jerrythen re-run the install command
Path Issues on Windows¶
If you see "path not found" when adding a local plugin source:
- Use forward slashes in Claude Code:
C:/Users/name/plugins/jerry - Avoid backslashes or environment variables in the Claude Code command
Updating¶
GitHub-installed users¶
Jerry updates when the source repository updates. To pull the latest:
Source name differs? Use the name from
/plugin marketplace list:/plugin marketplace update <name-from-list>.Auto-updates: Community marketplaces like Jerry have auto-update disabled by default. To enable automatic updates at startup: run
/plugin, go to the Marketplaces tab, select your Jerry source, and enable auto-update.
Local clone users¶
Then refresh in Claude Code:
Source name differs? Use the name from
/plugin marketplace list.
Uninstallation¶
Remove the Plugin¶
Source name differs? Use the name from
/plugin marketplace list:/plugin uninstall jerry@<name-from-list>.
Remove the Plugin Source¶
Not sure of the source name? Run
/plugin marketplace listto check.Note: Removing a marketplace source will uninstall any plugins you installed from it.
Delete Local Files (Optional)¶
Only applicable if you used the local clone method:
macOS/Linux:
Windows PowerShell:
That's it. Clean slate.
Getting Help¶
If something's broken, file it. If something's confusing, file that too. The docs get better when you tell us where they fall short.
- GitHub Issues: github.com/geekatron/jerry/issues
- Documentation: jerry.geekatron.org
- Claude Code Help: Run
/helpin Claude Code - Claude Code Plugin Docs: code.claude.com/docs/en/discover-plugins
License¶
Jerry Framework is open source under the Apache License 2.0.