Task: Add compass claude, a systemd-scoped Claude Code launcher
Table of Contents
This page documents a task in the Compass quality-of-life improvements story. It captures the goal, current status, acceptance, and any notes or results.
Goal
Add a `compass claude` subcommand that launches Claude Code inside a transient systemd –user scope, so systemd-oomd evaluates a runaway session as its own kill candidate instead of taking down whatever process spawned it (e.g. Emacs, whose child processes otherwise inherit its cgroup).
Status
| Field | Value |
|---|---|
| State | DONE |
| Parent story | Compass quality-of-life improvements |
| Now | Implemented, verified locally, PR pending. |
| Waiting on | Nothing. |
| Next | Raise PR, trigger review. |
| Last touched | 2026-07-29 |
Acceptance
- `compass claude` forwards all arguments to the real `claude` binary unchanged.
- On a host with a user systemd manager, the session runs as a transient scope under `app-claude.slice`; the slice unit is deployed to `~/.config/systemd/user/` automatically on first use or when the checked-in source changes.
- On a host without a usable user systemd manager, falls back to an unscoped exec rather than failing.
- Regular `claude` invocations are unaffected — this is opt-in.
Plan
(Implementation strategy. Written when work starts; key decisions
are distilled into the parent story's * Decisions at close, but the
plan itself stays — it is the historical record of what we did.)
Notes
Test Scenarios
Manual QA scenarios (scaffolded via compass add test_scenario, run
through the QA Validation Runner panel) that verify this task. Link
new ones here as they're created; the scenario doc itself links back
via its "Verifies task" field.
| Scenario | State | Notes |
|---|---|---|
PRs
| PR | Title |
|---|---|
| #1730 | [compass] Add compass claude, a systemd-scoped Claude Code launcher |
Review
| # | Comment summary | File | Decision | Notes |
|---|---|---|---|---|
| 5115067494 | Add "claude" to `_KNOWN_COMMANDS` typo-suggestion list | compass.py | Fixed | Added; `compass cladue` now suggests `compass claude` |
| 5115067758 | Stray leading backslash in slice unit | app-claude.slice | Fixed | Removed |
| 5115068768 | Unused `project_root` parameter in `run()` | compass_claude.py | Declined | Matches the existing `run_client(argv, project_root)` call-site convention across compass_*.py modules |
Result
Added `projects/ores.compass/src/compass_claude.py` (dispatched from `compass.py`) and the checked-in slice unit `projects/ores.compass/src/systemd/app-claude.slice`. Verified manually: `compass claude –version` deploys/refreshes the slice and runs inside an active `claude-<pid>.scope` (confirmed via `systemctl –user list-units`); re-running is a no-op on the slice file; `compass lint` passes. Documented in `doc/recipes/compass/how_do_i_launch_claude_in_a_systemd_scope.org`. Python-only change — no C++ build/ctest required.