User Manual Plain-language guide to what this does, how to use it, and what to do when something goes wrong.

What is this?

stack installs three tools that work together to make Claude Code more reliable, more self-aware, and more controlled. You run one command — /stack — and it sets up all three in the right order with the right wiring.

Once installed, these tools run automatically in the background every time you use Claude Code. You don't need to think about them during normal use. They change how Claude behaves, not what you ask it to do.

ℹ

New to Claude Code? Claude Code is Anthropic's command-line tool for using Claude as a coding assistant in your terminal. This manual assumes you already have it installed.

The three tools

🧠

Longhand

By Wynelson94 · github.com/Wynelson94/longhand

By default, Claude Code forgets everything when you close a session. Longhand fixes this. It saves every conversation to a database on your computer and gives Claude a way to search those past sessions. When you start a new conversation, Claude can recall what you worked on before — decisions made, bugs found, files changed.

What you'll notice: Claude will sometimes reference previous conversations without you prompting it. You can also ask Claude directly: "What did we work on last week?" and it will know.

Privacy: Everything is stored locally on your machine. Nothing is sent to the cloud. The database lives in your home directory.

Memory Layer

🔲

Context-Mode

By scottconverse · github.com/scottconverse/context-mode

When Claude runs a command — reading a file, running a test, fetching a web page — the raw output normally flows directly into the conversation and takes up space. On large codebases or long sessions, this causes Claude to start forgetting earlier parts of the conversation.

Context-Mode intercepts those outputs and processes them in a sandbox. Claude gets a structured summary instead of the raw dump. The conversation stays focused.

What you'll notice: Sessions run longer before hitting context limits. Claude is less likely to lose track of things from earlier in a conversation.

What it doesn't do: It doesn't change Claude's answers or hide information. It filters noise, not content.

Context Layer

🔒

Hardgate

By scottconverse · github.com/scottconverse/hardgate

Hardgate lets you define tools that Claude is not allowed to use without your explicit approval — pushing to GitHub, deleting files, running database migrations, whatever you choose. When Claude tries to use a blocked tool, it stops and asks you. You decide whether to proceed.

What you'll notice: Before certain risky operations, Claude will pause and ask rather than act. This is intentional.

No blocked tools by default. Hardgate installs the enforcement infrastructure. You choose the rules during the interactive install step.

Enforcement Layer

How they work together

Each tool hooks into a different Claude Code lifecycle event. They don't conflict with each other, and if one is misconfigured, the others continue working independently.

EVENT TOOL ACTION ───────────────────────────────────────────────────────────────── SessionStart Hardgate Reminds Claude of its blocked tools UserPromptSubmit Longhand Records your message to local database (every message) PreToolUse Hardgate Checks tool against the blocked list (before every Context-Mode Runs tool in sandbox, returns a clean tool call) summary instead of raw output SessionEnd Longhand Saves full session to searchable memory (on close)

Request flow in detail

1. You type a message │ ▼ 2. UserPromptSubmit fires └─ Longhand records prompt to database 3. Claude decides to use a tool (e.g. run a bash command) │ ▼ 4. PreToolUse — Hardgate checks first ├─ Tool is on the blocked list? │ YES ─▶ exit 2 · tool call cancelled · Claude tells you │ NO ─▶ continues │ ▼ 5. PreToolUse — Context-Mode intercepts └─ Runs tool in sandbox subprocess Produces structured summary Claude receives summary, not raw output 6. Claude formulates its response 7. You close the session │ ▼ 8. SessionEnd fires └─ Longhand saves full session · indexed for future recall

Config file layout

All three tools write into ~/.claude/settings.json. The stack installer creates a timestamped backup before touching anything.

~/.claude/settings.json ├── hooks │ ├── SessionStart ← Hardgate reminder │ ├── UserPromptSubmit ← Longhand prompt hook │ ├── PreToolUse ← Hardgate exit-2 enforcement │ │ Context-Mode (Bash, Read, WebFetch + 6 more) │ └── SessionEnd ← Longhand session ingest └── mcpServers ├── longhand ← memory query server └── context-mode ← sandbox execution server

Before you start

You'll need the following before installing:

Requirement	How to check	Where to get it
Python 3.10+	Run `python --version`	python.org/downloads
Node.js 18+	Run `node --version`	nodejs.org
Claude Code	Run `claude --version`	anthropic.com/claude-code
stack repo cloned	`ls ~/stack/scripts/verify.py`	See step 1 below
bash shell (Option B only)	Git Bash or WSL on Windows; Terminal on Mac	gitforwindows.org

✓

Windows users: Option A (standalone installer) runs natively on Windows — no Git Bash or WSL required. Option B (the /stack skill) requires Git Bash or WSL because the skill uses bash syntax.

There are two ways to install the stack. Choose the one that fits your situation.

Option A — Standalone installer Recommended · no Claude Code session needed

Run install.py directly from your terminal. Works on macOS, Linux, and Windows. No open Claude Code session required.

Clone the repo

git clone https://github.com/scottconverse/stack
cd stack

Run the installer

macOS / Linux:
```
bash install.sh
```
Windows: Double-click install.bat, or from any terminal:
```
python install.py
```
ℹ
One interactive step: When the installer reaches Hardgate, it will pause and give you instructions to run /hard-gate inside a Claude Code session. Follow the on-screen prompt, then press Enter to continue.
Restart Claude Code

When verification passes, close and reopen Claude Code. The tools take effect on the next session.
Verify runtime health
```
longhand doctor
claude mcp list
```
longhand doctor should show green. claude mcp list should include both longhand and context-mode.

Option B — `/stack` Claude Code skill Requires an open Claude Code session

Install from inside an active Claude Code session using the /stack skill command.

Clone the repo

The full repo must be present on your machine. Don't copy just the skill file — the installer requires scripts/verify.py alongside it.
```
git clone https://github.com/scottconverse/stack
```
Add the skill to Claude Code

Point Claude Code to the skill file by adding skills/stack.md to your Claude Code skill path.
Open a Claude Code session and run /stack
```
claude
/stack
```
ℹ
One interactive step: Hardgate requires you to run /hard-gate and reply before the installer continues.
Restart Claude Code

When verification passes, close and reopen Claude Code.
Verify runtime health
```
longhand doctor
claude mcp list
```

Re-running safely

Both the standalone installer and the /stack skill are safe to run again at any time. Before installing anything, the installer checks which tools are already fully set up and skips them. Only tools that are missing or partially installed get re-run.

Each run creates a fresh timestamped backup of your config — multiple runs produce independent snapshots, not overwrites.

What the verifier checks

After installation, scripts/verify.py runs automatically and reports on six checks. You can also run it standalone at any time:

python scripts/verify.py

Check	Status	What to do if it fails
Longhand SessionEnd hook	✓ required	Run `longhand setup`
Longhand UserPromptSubmit hook	✓ required	Run `longhand prompt-hook install`
Context-Mode PreToolUse hooks	✓ required	Run `node install.js` from your context-mode directory
Longhand MCP server	✓ required	Run `claude mcp add longhand -s user -- longhand mcp-server`
Context-Mode MCP server	✓ required	Run `node install.js` from your context-mode directory
Hardgate enforcement	⚠ warning only	Run `/hard-gate` and select an enforcement target

The verifier prints the exact retry command for each failure. The exit code tells you what happened:

Exit code	Meaning	Action
`0`	All required checks pass	Restart Claude Code and you're done
`1`	One or more checks failed; config files are intact	Follow the retry commands printed
`2`	A config file is malformed (corrupted)	Both files are automatically restored from backup

When things go wrong

`install.py` can't find Python

On Windows, make sure Python 3.10+ is installed and on your PATH. Try running:

python --version

If that fails, download Python from python.org/downloads and check "Add Python to PATH" during install. Then re-run install.py.

`install.py` fails mid-way through

The installer is safe to re-run. It checks what's already installed and picks up where it left off. Run it again:

python install.py

If the same step keeps failing, run the verifier to see which check is failing and what the exact retry command is:

python install.py --verify

"verify.py not found"

You copied just the skill file instead of cloning the full repo. Fix it:

git clone https://github.com/scottconverse/stack
export STACK_DIR=/path/to/stack

Then run /stack again.

Verifier exits with code 2

One of your Claude config files has been corrupted. The installer detects this automatically and restores both config files from the timestamped backup it took before the install started. Your settings are returned to exactly the state they were in before you ran /stack. Then retry each failed step using the commands shown in the verifier output.

`longhand doctor` shows a failure

Longhand's MCP server is registered in your config but not responding. Try:

longhand setup

If that doesn't fix it, confirm Python 3.10+ is still on your PATH: python --version

`claude mcp list` doesn't show longhand or context-mode

The MCP server entries are missing. Re-run the relevant install command:

For Longhand

claude mcp add longhand -s user -- longhand mcp-server

For Context-Mode

node install.js

Claude isn't recalling past sessions

Longhand may be installed but hasn't ingested any history yet. Run:

longhand ingest-session

Then start a fresh Claude Code session.

A tool is only partially installed

Run /stack again. The installer detects partial installs and re-runs that tool's installer from scratch.

⚠

Known limitation: The verifier checks that config entries are present, not that MCP servers are live. After a successful install, always run longhand doctor and claude mcp list to confirm runtime health — not just config presence.

Restoring your original config

Every time you run /stack, it saves a timestamped backup of both config files:

~/.claude/settings.json.stack-backup-YYYYMMDD-HHMMSS
~/.claude.json.stack-backup-YYYYMMDD-HHMMSS

To find your most recent backup:

ls -t ~/.claude/settings.json.stack-backup-* | head -1

To restore it manually:

cp ~/.claude/settings.json.stack-backup-YYYYMMDD-HHMMSS ~/.claude/settings.json

Glossary

Claude Code: Anthropic's command-line interface for Claude. Runs in your terminal and lets you give Claude tasks that involve your local files, code, and development tools.
Hook: A command that Claude Code runs automatically at certain points — before a tool runs, after a session ends, when you submit a prompt. Hooks are how Longhand, Context-Mode, and Hardgate connect into Claude Code's workflow.
MCP server: A background process that Claude Code connects to and queries during a session. Longhand and Context-Mode each run as MCP servers so Claude can call them directly.
settings.json: Claude Code's main configuration file, stored at ~/.claude/settings.json. Hook definitions and MCP server registrations live here.
Context window: The amount of text Claude can hold in active memory at one time. When it fills up, Claude starts losing track of earlier parts of the conversation. Context-Mode helps delay this.
SessionEnd hook: A hook that runs when you close a Claude Code session. Longhand uses this to save the full session to its database.
PreToolUse hook: A hook that runs before Claude uses any tool. Context-Mode and Hardgate both use this — Hardgate to block forbidden tools, Context-Mode to sandbox output.
UserPromptSubmit hook: A hook that runs every time you send a message. Longhand uses this to record each prompt as it arrives.
Idempotent: Safe to run multiple times with the same result. Running /stack twice does not double-install anything.
Exit code: A number a program returns when it finishes. Exit 0 means success. Exit 1 means something failed. Exit 2 means a config file is malformed and needs restoration.

User Manual Plain-language guide to what this does, how to use it, and what to do when something goes wrong.

What is this?

The three tools

Longhand

Context-Mode

Hardgate

How they work together

Request flow in detail

Config file layout

Before you start

Option A — Standalone installer Recommended · no Claude Code session needed

Clone the repo

Run the installer

Restart Claude Code

Verify runtime health

Option B — /stack Claude Code skill Requires an open Claude Code session

Clone the repo

Add the skill to Claude Code

Open a Claude Code session and run /stack

Restart Claude Code

Verify runtime health

Re-running safely

What the verifier checks

When things go wrong

install.py can't find Python

install.py fails mid-way through

"verify.py not found"

Verifier exits with code 2

longhand doctor shows a failure

claude mcp list doesn't show longhand or context-mode

Claude isn't recalling past sessions

A tool is only partially installed

Restoring your original config

Glossary

Option B — `/stack` Claude Code skill Requires an open Claude Code session

Open a Claude Code session and run `/stack`

`install.py` can't find Python

`install.py` fails mid-way through

`longhand doctor` shows a failure

`claude mcp list` doesn't show longhand or context-mode