openwpm Crosslink Guide
Crosslink is a local-first issue tracker designed for AI-assisted development. Data lives in .crosslink/issues.db (SQLite); state syncs via the crosslink/hub git branch. Read this skill when the workflow involves any crosslink command, when the crosslink-behavioral-guard hook fires, or when starting/ending a session.
Hook awareness — the things that bite
These are not in the CLI --help output but matter constantly:
crosslink issue close auto-appends to CHANGELOG.md
Closing an issue triggers a hook that adds a one-line entry to the workspace's CHANGELOG.md under ### Changed (or ### Fixed for bug-labeled issues). For meta-work that shouldn't be in the release notes (skill edits, settings tweaks, CHANGELOG cleanup itself), this is pollution.
Fix: pass --no-changelog to skip:
crosslink issue close 643 --no-changelog
The recursive trap: if you close an issue without --no-changelog, then close a follow-up issue to clean up the entry, that close also auto-appends. Either use --no-changelog from the start, or remove the line directly via Edit rather than another crosslink close.
crosslink quick doesn't take --no-changelog
Only close triggers the auto-CHANGELOG hook. quick and create do not, so no --no-changelog flag exists on them.
Session must be started before session work <id> succeeds
crosslink session work 642
# Error: No active session. Use 'crosslink session start' first.
Always pair them:
crosslink session start && crosslink session work <id>
--work flag on quick is silently a no-op without an active session
crosslink quick "..." -p high -l bug
# WARN: --work specified but no active session
The issue gets created but isn't marked as the current focus. Same fix: session start first.
Labels matter for hook routing
Bug-labeled issues land under ### Fixed in CHANGELOG; everything else under ### Changed. The chore, docs, refactor labels currently do not exempt the entry from CHANGELOG (use --no-changelog).
Core workflow
# 1. Start session (see what the last session handed off)
crosslink session start
# 2. Create or pick an issue to work on
crosslink quick "Title" -p high -l bug # create + claim lock + start working
# OR
crosslink issue list -s open # see existing issues
crosslink session work <id> # pick one
# 3. Document as you work
crosslink issue comment <id> "Approach: ..." --kind plan
crosslink issue comment <id> "Chose X over Y because ..." --kind decision
# 4. End session with handoff notes
crosslink session end --notes "What's done, what's next, blockers"
Issue management
Creating
crosslink issue create "Title" -p medium # basic
crosslink quick "Title" -p high -l bug # create + auto-claim lock + work
crosslink subissue <parent-id> "Child title" # create under a parent
Querying
crosslink issue list # open issues (default)
crosslink issue list -s all # include closed
crosslink issue list -l bug -p high # filter by label and priority
crosslink issue search "keyword" # full-text
crosslink issue show <id> # full details
crosslink issue tree # hierarchy view
crosslink issue next # suggest what to work on
Lifecycle
crosslink issue update <id> -t "new title" -p high # update title/priority
crosslink issue close <id> # close + add to CHANGELOG
crosslink issue close <id> --no-changelog # close + skip CHANGELOG
crosslink issue close-all # close all matching filters
crosslink issue reopen <id> # reopen if needed
crosslink issue delete <id> --force # permanent delete
crosslink issue tested <id> # mark tests run (resets reminder)
Comments — typed for audit trails
crosslink issue comment <id> "text" --kind plan # what you intend to do
crosslink issue comment <id> "text" --kind decision # why you chose this approach
crosslink issue comment <id> "text" --kind observation # something you discovered
crosslink issue comment <id> "text" --kind blocker # what's blocking progress
crosslink issue comment <id> "text" --kind resolution # how a blocker was resolved
crosslink issue comment <id> "text" --kind result # what was delivered
Labels and relations
crosslink issue label <id> bug # add label
crosslink issue unlabel <id> bug # remove label
crosslink issue block <id> <blocker-id> # mark dependency
crosslink issue unblock <id> <blocker-id> # remove blocking
crosslink issue blocked # show blocked
crosslink issue ready # show unblocked
crosslink issue relate <id1> <id2> # link related
crosslink issue related <id> # list related
Interventions
For recording when you had to deviate from the planned approach:
crosslink issue intervene <id> "description" --trigger <type> --context "what you were doing"
Sessions
crosslink session start # begin work, see last handoff
crosslink session work <id> # set current focus
crosslink session status # check what you're working on
crosslink session last-handoff # show previous session's notes
crosslink session action "did X" # breadcrumb before context compression
crosslink session end --notes "context for next session"
Always end with --notes. The next session reads them via session start — terse notes there save real reorientation time.
Locks
Crosslink uses optimistic locking on issues so multiple agents don't collide.
crosslink locks list # active locks
crosslink locks check <id> # is this issue locked?
crosslink locks claim <id> # claim
crosslink locks release <id> # release
crosslink locks steal <id> # take a stale lock (be careful)
crosslink quick and crosslink session work auto-claim. crosslink issue close releases.
Time tracking
crosslink timer start <id> # start
crosslink timer stop # stop current
crosslink timer show # current status
Knowledge base
Shared markdown pages on the crosslink/knowledge branch:
crosslink knowledge add "page-slug" --body "content"
crosslink knowledge show <slug>
crosslink knowledge list
crosslink knowledge edit <slug> --body "new content"
crosslink knowledge remove <slug>
crosslink knowledge search "query"
crosslink knowledge sync # pull from remote
crosslink knowledge import <path> # bulk import markdown
Kickoff (agent launcher)
crosslink kickoff run <issue-id> # launch agent in worktree
crosslink kickoff launch # interactive pipeline wizard
crosslink kickoff status # check running
crosslink kickoff logs <id>
crosslink kickoff stop <id>
crosslink kickoff list # all agents (worktrees/tmux/docker)
crosslink kickoff cleanup # remove completed/stale
crosslink kickoff graph # branch topology
Design-driven workflow:
crosslink kickoff plan <design-doc> # gap analysis vs codebase
crosslink kickoff show-plan <slug> # display gap report
crosslink kickoff report <id> # spec validation report
Swarm (multi-agent coordination)
# Lifecycle
crosslink swarm init <design-doc> # init from design doc
crosslink swarm status # agents, phases, progress
crosslink swarm resume # reconstruct + show next
crosslink swarm list # active + archived
crosslink swarm archive
crosslink swarm reset
# Phases
crosslink swarm launch # launch all agents for a phase
crosslink swarm gate # run test suite as gate
crosslink swarm checkpoint # record after phase done
crosslink swarm merge # merge worktrees into one branch
# Planning
crosslink swarm plan # multi-phase across budget windows
crosslink swarm plan-show
crosslink swarm config # budget params
crosslink swarm estimate # wall-clock cost estimate
crosslink swarm harvest # update cost history
# Review pipeline
crosslink swarm review # parallel review agents
crosslink swarm fix # parallel fix agents
crosslink swarm pipeline # full review→fix
crosslink swarm review-status
crosslink swarm review-continue
Container execution
crosslink container build # build agent image
crosslink container start <worktree> # start for a worktree
crosslink container ps # list running
crosslink container logs <id> # stream
crosslink container stop <id>
crosslink container rm <id>
crosslink container kill <id> # stop + remove
crosslink container shell <id> # exec shell
crosslink container snapshot <id> # save as cached image
Agent identity and trust
# Agent
crosslink agent init # initialize identity
crosslink agent status # show current
crosslink agent prompt <session> "message" # send to tmux agent
crosslink agent bootstrap # bootstrap in new repo
# Trust (signing keys)
crosslink trust approve <fingerprint>
crosslink trust revoke <fingerprint>
crosslink trust list
crosslink trust pending # awaiting approval
crosslink trust check <agent>
Design documents
crosslink design "feature description" # start design session
crosslink design --issue <id> # context from crosslink issue
crosslink design --gh-issue <num> # context from GitHub issue
crosslink design --continue <slug> # resume existing draft
Milestones
crosslink milestone create "v1.0"
crosslink milestone list
crosslink milestone show <id>
crosslink milestone add <milestone-id> <issue-id>
crosslink milestone remove <milestone-id> <issue-id>
crosslink milestone close <id>
crosslink milestone delete <id>
Archive
crosslink archive add <id> # archive a closed issue
crosslink archive remove <id> # unarchive
crosslink archive list
crosslink archive older <days> # bulk-archive old closed
Configuration
crosslink config # interactive walkthrough
crosslink config --preset team # team preset
crosslink config --preset solo # solo preset
crosslink config show # all values + defaults
crosslink config get <key>
crosslink config set <key> <value>
crosslink config list # keys with descriptions
crosslink config reset
crosslink config diff # drift from defaults
Workflow and diagnostics
crosslink workflow diff # policy files vs embedded defaults
crosslink workflow trail <id> # chronological comment trail
crosslink context measure # context injection token cost
crosslink context check # files deployed correctly?
crosslink cpitd scan # scan for code clones
crosslink cpitd status
crosslink cpitd clear
Style syncing
crosslink style set <repo-url> # set house style source
crosslink style sync # pull latest
crosslink style diff # drift from house
crosslink style show # current config
crosslink style unset
Infrastructure
crosslink init # initialize in a repo
crosslink sync # sync from remote
crosslink compact # event compaction
crosslink prune # prune hub/knowledge history
crosslink export # JSON/markdown export
crosslink import <file> # import from JSON
crosslink daemon start|stop|status # background daemon
crosslink migrate to-shared|from-shared|rename-branch # schema migrations
Integrity / troubleshooting
crosslink integrity counters --repair # fix counter drift
crosslink integrity hydration --repair # rehydrate SQLite from JSON
crosslink integrity locks # find stale/orphan locks
crosslink integrity schema # verify schema version
crosslink integrity layout # detect mixed V1/V2 hub layout
crosslink integrity sign-backfill # sign unsigned with human key
UI
crosslink tui # interactive terminal dashboard
crosslink mc # tmux mission control
crosslink serve # web dashboard server
Issue ID formats
#42— hub-synced, positive display IDL3— local-only (not yet pushed to hub)- Both formats work everywhere:
crosslink show 42,crosslink show L3
Priorities
critical > high > medium > low
Global flags (work on most subcommands)
--quiet/-q— minimal output (for scripting)--json— machine-readable output--log-level <error|warn|info|debug|trace>— diagnostic output level--log-format <text|json>— log format
When meta-work shouldn't go in CHANGELOG
Tag the close with --no-changelog for any of these:
- Skill edits in
~/.claude/ - Settings.json changes
- CHANGELOG cleanup itself
- Documentation-only PRs that don't ship to users
- Issue tracker hygiene (closing audit/tracking issues whose deliverables already shipped)
- Any
chore-labeled work (the auto-routing currently doesn't exempt these)
If the auto-entry already landed, remove it via Edit on CHANGELOG.md directly. Don't open another issue to "fix the CHANGELOG entry" — that just adds another entry. The recursion is real.