CLAUDE.md

See AGENTS.md for the canonical agent instructions — working style, repo layout, version-control rules, the dev/ workflow, and the .claude/skills/ index apply to every agent tool, not just Claude Code.

The sections below are Claude Code-specific additions that stack on top of AGENTS.md.

Claude Code-specific — sub-agent parallelization

Parallelize independent work via sub-agents — aggressively. Many investigations are wide but shallow: "how do X and Y differ?", "trace the data flow across these five files", "find every caller of Foo across <SOURCE_ROOT>/** and any reference implementations". When sub-questions don't depend on each other, spawn multiple Agent calls in a single response so they run concurrently. Don't run them serially, and don't do them yourself when a sub-agent can.

Default picks:

Explore — broad grep-heavy searches across <SOURCE_ROOT>/** or third-party reference trees.
general-purpose — multi-step investigations that interleave reading, grepping, and reasoning.
Plan — architectural scoping for a phase or sub-phase before implementation.

Sub-agents also keep the main context clean when a search would otherwise dump thousands of lines. When in doubt whether to parallelize — do it.

Thoroughness and speed aren't at odds — sub-agents buy more reading per wall-clock second. The user is happy to wait for a slower, better-grounded answer, but they're not happy about serialized work that could have run in parallel.

Template-maintenance — when working on this template itself

These items apply when editing template-jj itself (the Go daemon, hook scripts, skills). They do not travel with the template when it's copied into a user's project.

Commit Daemon (`jj-commitd`)

Architecture: bash hook client → Unix socket → Go daemon (jj-commitd) → jj CLI.
Debounce: edits within 3 seconds are batched into one commit (configurable via JJ_HOOK_DEBOUNCE_SEC).
Session PID: hook passes $PPID to the daemon for accurate session-liveness tracking.
Daemon log: /tmp/jj-commitd-<repo_id>.log — check here for commit/socket errors.
Fallback: if the binary is not on PATH, the hook falls back to file-tracking-only mode (commits only at session end).
Legacy cleanup: on startup, the daemon sweeps and removes orphaned legacy tracking files (/tmp/jj-claude-*-files).
Cross-session conflicts are detected and logged (returned in post-edit response).
Session inventory: session-start returns the list of all other active sessions and their tracked files.

Environment variables

JJ_HOOK_DEBOUNCE_SEC — debounce interval in seconds (default: 3, max: 30).
JJ_HOOK_STALE_MIN — stale-session reap threshold in minutes (default: 30).
JJ_HOOK_AUTO_SQUASH — set to 1 to squash session wip commits automatically at session end.

Git remote

origin pushes to forgejo.zerova.net. This is a template-maintenance detail specific to template-jj's own repo — when the template is copied into a user's project, drop this bullet or replace the URL with the target project's remote.
Don't add Co-Authored-By lines in commits. This rule is a general convention and should be kept when the template is copied.

3.3 KiB Raw Permalink Blame History