Optional helpers¶
Four small helpers ship with the package to make the Shadow Git journal usable from a terminal and from the agent itself: two CLIs and two agent templates.
| Helper | Installed to | What it does |
|---|---|---|
shadow-git |
~/.local/bin/shadow-git |
Git wrapper for the per-project shadow repositories — log, show, diff, blame, plus project/session listing and full-text search |
shadow-query |
~/.local/bin/shadow-query |
Runs read-only SQL against the shadow DuckDB via the server's /api/shadow-db/sql endpoint (handles auth and formatting) |
shadow-git-helper |
~/.claude/agents/shadow-git-helper.md (+ ~/.codex/agents/shadow-git-helper.toml) |
Agent template — a "code archaeologist" for file history, diffs and blame in the shadow repo |
shadow-db-helper |
~/.claude/agents/shadow-db-helper.md (+ ~/.codex/agents/shadow-db-helper.toml) |
Agent template — a journal researcher that queries the turn database (prompts, summaries, decisions, costs) via shadow-query |
The agent templates are installed for every provider that is enabled and available on the server, each in that provider's own format — Markdown for Claude Code, a TOML role file for Codex. A provider whose CLI isn't installed gets nothing.
All targets are user-scoped: no sudo, no $PATH edits, no shell-rc changes. The Docker image installs the CLIs and the Claude agents at build time; the in-app installer adds the other providers' copies.
You'll likely need the full path — ~/.local/bin may not be on your $PATH
The installer creates ~/.local/bin/ and copies the scripts in, but it never touches your $PATH and doesn't warn you if the directory isn't on it. On many distros it already is; on macOS and plenty of others it isn't, and a bare shadow-git log then just reports "command not found".
The script's closing "no PATH change is needed" line is true for the agent, which invokes the CLI by absolute path — not for you at a prompt. That's also why the in-app instructions tell you to run ~/.local/bin/shadow-git log. Either use the full path, or add the directory yourself:
Helpers follow the server that launched them
The server exports PAINAPPLE_CODE_HOME, PAINAPPLE_URL, PAINAPPLE_AUTH_CONFIG and (for an https loopback URL) PAINAPPLE_CACERT to everything it starts — agents, subagents and terminal tabs. Inside a session, shadow-git therefore reads the right data home (the container's /data, a host profile's ~/.painapple-code/profiles/NAME/) and shadow-query talks to the right server, whatever its port, bind or TLS mode. No credential is exported; shadow-query reads the token from the config file on each call.
In a plain shell outside a session, shadow-git looks in ~/.painapple-code and every ~/.painapple-code/profiles/*/, uses the most recently written repo for the project, and says on stderr which one it picked when there was a choice. Set PAINAPPLE_CODE_HOME to choose explicitly.
On native Windows
shadow-git and shadow-query are bash scripts, so they need a bash. If the installer finds one — Git for Windows counts, and is looked for next to git.exe — it installs both scripts and generates a small .cmd wrapper beside each, which is what lets PowerShell run shadow-git log by name. If no bash is found, the two CLIs are skipped (the Settings panel marks them "Not available here" rather than nagging that they're out of date) and only the agents install — which is the part that matters for # autocomplete.
Installing¶
From the UI¶
The status bar always shows an auto-journal pill, so the feature stays discoverable — it just changes label to report state: Auto-journal when everything is current, Helpers outdated, or Helpers not installed. Click it to open the helpers-install widget (the auto-journal control center). It shows per-file install/freshness state, installs or updates them all with one click (POST /api/app/helpers/install), and also holds the per-project journal toggles.
What is conditional is the widget opening by itself: it auto-pops when anything is outdated (always) or missing (unless you've ticked "Don't show again"), and never when everything is current.
The Install button overwrites local edits
The UI always installs with --update, so clicking Install/Update replaces the installed copies with the bundled ones — any tweaks you made to ~/.local/bin/shadow-git are lost. The bare CLI invocation is the safe one: it skips files that already exist unless you pass --update yourself.
From the script¶
On a host install, run the bundled script yourself (path shown for a repo checkout; on a pip install it lives in the installed package's tools/ directory):
src/painapple_code/tools/install-helpers.sh # install (skip files already present)
src/painapple_code/tools/install-helpers.sh --update # overwrite with the packaged version (alias: --force)
src/painapple_code/tools/install-helpers.sh --uninstall # remove installed files
src/painapple_code/tools/install-helpers.sh --dry-run # preview without changing anything
src/painapple_code/tools/install-helpers.sh --help # usage (-h works too)
All three scripts take --help / -h; shadow-git also answers a bare shadow-git help.
The server tracks freshness by content hash (GET /api/app/helpers/status), so after an upgrade the UI pill reappears when the installed copies are stale.
shadow-git¶
Wraps git pointed at the current project's shadow repository ($PAINAPPLE_CODE_HOME/projects/{hash}/shadow-git/, default ~/.painapple-code). Any git command passes through; a few extras are built in:
shadow-git log --oneline -20 # last 20 journal commits
shadow-git log --grep="auth" # search commit messages
shadow-git log -- src/app.js # history of one file
shadow-git show HEAD~2 # inspect a commit
shadow-git diff HEAD~3..HEAD # compare changes
shadow-git projects # all projects that have a shadow repo
shadow-git sessions # sessions in the current project
shadow-git branches # shadow branches with commit counts
shadow-git search <pattern> # full-text search across all commits
shadow-git snapshot [msg] # commit a baseline of all files
Project detection uses the current directory; override with SHADOW_PROJECT=/path/to/project. shadow-git snapshot skips files larger than 50 MB — raise or lower that with SHADOW_MAX_FILE_MB (0 disables the cap), mirroring the server's own shadow_git.max_file_size_mb.
shadow-query¶
Sends SQL to the server's read-only DuckDB endpoint (the server owns the database's write lock, so all reads go through HTTP):
shadow-query 'SELECT count(*) FROM turns'
shadow-query 'SELECT id, cost FROM turns ORDER BY cost DESC LIMIT 5'
shadow-query --json 'SELECT * FROM turns LIMIT 1' | jq
shadow-query - <<'EOF'
SELECT date_trunc('day', started_at) AS day, count(*) AS n
FROM turns GROUP BY day ORDER BY day DESC LIMIT 7
EOF
| Variable | Purpose |
|---|---|
PAINAPPLE_URL |
Server base URL (default http://localhost:8765; set automatically inside a session) |
PAINAPPLE_AUTH_CONFIG |
Config file to read the API token from (default ~/.config/painapple-code/config.yaml; set automatically inside a session) |
PAINAPPLE_CACERT |
Certificate to trust for an https URL with a self-signed cert (set automatically when needed) |
PAINAPPLE_TOKEN |
API token override; otherwise read from the config file |
Output is TSV by default, JSON with --json. --tsv asks for the default explicitly, and --format json|tsv (or --format=json) does the same thing if you prefer that spelling. A - argument reads the SQL from stdin. The endpoint rejects anything that isn't a read (no INSERT/UPDATE/DDL), and — worth knowing before you pipe into jq — every value comes back as a string.
Helper agents¶
shadow-git-helper¶
An agent template installed into ~/.claude/agents/ (and ~/.codex/agents/ when Codex is enabled), giving every Claude session (pAInapple Code or plain CLI) a specialist for code archaeology: file history, changes by session, blame analysis, tracing when and why code changed.
Use it by delegating from a normal prompt:
Consult with shadow-git-helper about when the auth middleware last changed and why.
Claude spawns the sub-agent, which digs through the shadow repo with the shadow-git CLI and reports back — keeping your main thread focused on the task instead of filling it with research output.
shadow-db-helper¶
A journal researcher that queries the turn database through shadow-query: what was asked, the per-turn summaries, decisions and findings, tags, costs and which files each turn touched. Pick it for questions about intent (“when did we decide to drop the CDN imports, and why?”); pick shadow-git-helper for questions about code (“what did this function look like last week?”).
Using them from Codex¶
Codex has no # picker for agents, so ask for one by name — “use the shadow-db-helper agent to find when we changed the login flow”. Codex subagents inherit the session's sandbox, and the sandboxed modes block all network access including loopback, so shadow-db-helper can reach the database only in Full access; in sandboxed modes it falls back to the shadow-git commit bodies, which carry the same journal. The Subagent model picker applies to the Claude copies only — Codex copies run on the session's model.