feat(min)!: re-parent session verbs under the session noun - #1008
Conversation
📝 WalkthroughWalkthroughSession lifecycle commands are routed under ChangesSession CLI migration
Estimated code review effort: 2 (Simple) | ~10 minutes Possibly related issues
Possibly related PRs
Suggested reviewers: Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches📝 Generate docstrings
Comment |
b25b803 to
3efe3b7
Compare
1690f6b to
f7b06d9
Compare
There was a problem hiding this comment.
Actionable comments posted: 7
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/concepts/loadouts.md`:
- Around line 166-169: Update the console examples in the loadouts
documentation, including both affected command blocks, to remove the `$` prompt
prefixes since they contain no output. Keep the commands themselves unchanged
and ensure the resulting Markdown passes the MD014 lint rule.
In `@docs/concepts/sessions.md`:
- Around line 67-69: Update the affected console examples in sessions.md,
including the block containing “min session activate --attach,” to remove $
prompt prefixes when no output is shown, or add representative output; ensure
all listed command blocks satisfy markdownlint-cli2 MD014.
In `@docs/guide/agents.md`:
- Around line 20-23: Update the shell command block in the agents guide to
resolve MD014 by removing the leading “$” prompts from both commands, or add
representative command output; preserve the existing commands and their
ordering.
In `@docs/guide/dev-shell.md`:
- Line 14: Remove the leading “$” prompts from the command-only shell fences in
dev-shell.md, including the command around “min session activate --attach .” and
the additionally referenced commands, while preserving them as shell commands
without adding output.
In `@docs/guide/setup.md`:
- Line 2: Update the guide description metadata to reference `min session
activate --attach .` instead of the non-attaching activation command, matching
the documented entry flow while preserving the existing setup summary.
In `@docs/reference/cli-min.md`:
- Line 58: Update the fenced command blocks in the CLI documentation at the
listed locations to specify a language, using shell for commands and console
where output is shown, so every newly added fence satisfies markdownlint MD040.
In `@docs/reference/cli.md`:
- Around line 29-33: Update the command examples in the “Command naming
convention” section to remove the undocumented “min completions install” example
or replace it with a documented noun/verb command, while preserving the
convention explanation and remaining valid examples.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 65c31f85-66c9-4f7a-a90f-4d92d96c1e1a
📒 Files selected for processing (32)
AGENTS.mdREADME.mdcrates/diagnostics/src/procs.rscrates/minimal/src/attach.rscrates/minimal/src/lib.rscrates/minimal/src/prompt.rscrates/minimal/tests/cli.rscrates/minimald/src/server.rscrates/minimald/src/session.rscrates/minimald/src/store.rscrates/op/src/project/init.rscrates/sessions/docs/COMPOSITION.mdcrates/sessions/example_project/minimal.tomlcrates/sessions/src/core/compose.rscrates/sessions/src/store.rscrates/sessions/src/wire/request.rsdocs/concepts/loadouts.mddocs/concepts/sessions.mddocs/guide/agents.mddocs/guide/dev-shell.mddocs/guide/setup.mddocs/reference/cli-min.mddocs/reference/cli.mddocs/reference/linux-host-setup.mddocs/reference/loadouts.mddocs/reference/minimal-dot-toml.mdjustfilescripts/bulk-upload-e2e.shscripts/e2e-attach-pty.pyscripts/kernel-bump-review.shscripts/session-e2e.shscripts/stress-session-e2e.sh
Move activate, attach, destroy, and rename under the session noun, continuing the <noun> <verb> sweep that #976 started with mip package. min ls, min stop, bare min, and the init/add/update passthroughs stay top-level as deliberate ergonomic exceptions, commented as such in the source so a later reader does not "fix" them. stop in particular acts on the daemon backend rather than any session. Nouns gain a visible singular/plural alias. Documents the convention itself in docs/reference/cli.md, so it is not re-derived from the command tree every time someone adds a command. BREAKING CHANGE: min activate, min attach, min destroy and min rename are now min session activate, min session attach, min session destroy and min session rename. Refs: #1005 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
f7b06d9 to
f79f504
Compare
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/guide/agents.md`:
- Around line 25-27: Update the session command guidance near the `min session
attach -c` documentation to enumerate all supported non-interactive command
paths: `min run <task>`, `min package build [args...]`, `min check [args...]`,
and the internal `git-receive-pack min://` path. Replace the claim that only
`min run` is accepted while preserving the instruction to launch the agent from
an attached shell for interactive use.
In `@docs/reference/cli-min.md`:
- Around line 17-23: Update the command-convention section in the CLI reference
to explicitly list bare “min dirs”, “min bug”, “min version”, and “min
completions” as deliberate standalone exceptions, while preserving the existing
noun/verb convention and previously documented exceptions.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 7c026af3-092f-480f-a157-41bfb4e7eb7f
📒 Files selected for processing (32)
AGENTS.mdREADME.mdcrates/diagnostics/src/procs.rscrates/minimal/src/attach.rscrates/minimal/src/lib.rscrates/minimal/src/prompt.rscrates/minimal/tests/cli.rscrates/minimald/src/server.rscrates/minimald/src/session.rscrates/minimald/src/store.rscrates/op/src/project/init.rscrates/sessions/docs/COMPOSITION.mdcrates/sessions/example_project/minimal.tomlcrates/sessions/src/core/compose.rscrates/sessions/src/store.rscrates/sessions/src/wire/request.rsdocs/concepts/loadouts.mddocs/concepts/sessions.mddocs/guide/agents.mddocs/guide/dev-shell.mddocs/guide/setup.mddocs/reference/cli-min.mddocs/reference/cli.mddocs/reference/linux-host-setup.mddocs/reference/loadouts.mddocs/reference/minimal-dot-toml.mdjustfilescripts/bulk-upload-e2e.shscripts/e2e-attach-pty.pyscripts/kernel-bump-review.shscripts/session-e2e.shscripts/stress-session-e2e.sh
🚧 Files skipped from review as they are similar to previous changes (21)
- crates/minimald/src/store.rs
- docs/reference/minimal-dot-toml.md
- scripts/e2e-attach-pty.py
- docs/reference/cli.md
- crates/sessions/example_project/minimal.toml
- crates/minimal/src/prompt.rs
- justfile
- crates/minimald/src/server.rs
- crates/sessions/src/store.rs
- crates/op/src/project/init.rs
- crates/minimald/src/session.rs
- crates/sessions/src/wire/request.rs
- scripts/stress-session-e2e.sh
- crates/sessions/docs/COMPOSITION.md
- docs/reference/loadouts.md
- crates/minimal/tests/cli.rs
- docs/guide/setup.md
- crates/diagnostics/src/procs.rs
- scripts/bulk-upload-e2e.sh
- scripts/session-e2e.sh
- crates/minimal/src/lib.rs
| Claude Code launches inside the session with your project's source code and a read-only system containing the `claude-code` binary and core utilities from `base`. The session has no additional access to anything on your host system unless you explicitly declare it. | ||
|
|
||
| Note that sessions are driven interactively: attaching needs a terminal, and the non-interactive `min attach -c` channel accepts only `min run <task>` invocations. Launch the agent from inside an attached shell as shown above, rather than scripting it from the host. | ||
| Note that sessions are driven interactively: attaching needs a terminal, and the non-interactive `min session attach -c` channel accepts only `min run <task>` invocations. Launch the agent from inside an attached shell as shown above, rather than scripting it from the host. |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Document all supported attach -c command paths.
This currently says the non-interactive channel accepts only min run <task>, but the daemon also accepts min package build [args...] and min check [args...] (plus the internal git-receive-pack min:// path). Update the guide so users are not incorrectly told that supported build/check automation is unavailable.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/guide/agents.md` around lines 25 - 27, Update the session command
guidance near the `min session attach -c` documentation to enumerate all
supported non-interactive command paths: `min run <task>`, `min package build
[args...]`, `min check [args...]`, and the internal `git-receive-pack min://`
path. Replace the claim that only `min run` is accepted while preserving the
instruction to launch the agent from an attached shell for interactive use.
| Commands are spelled `min <noun> <verb>`, and every noun accepts its singular | ||
| and plural form (`session`/`sessions`, `provider`/`providers`, | ||
| `loadout`/`loadouts`). Bare `min` and a handful of bare verbs (`ls`, `stop`, | ||
| `init`, `add`, `update`) survive at the top level as deliberate ergonomic | ||
| exceptions, called out as such below; see | ||
| [the CLI convention](./cli.md#command-naming-convention) for the rule and the | ||
| full list of exceptions. |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Document the remaining standalone commands.
This section claims the min <noun> <verb> convention and lists the full exceptions, but this file also documents bare min dirs, min bug, min version, and min completions. Either scope the convention to the command families it governs or explicitly document these standalone commands as exceptions.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/reference/cli-min.md` around lines 17 - 23, Update the
command-convention section in the CLI reference to explicitly list bare “min
dirs”, “min bug”, “min version”, and “min completions” as deliberate standalone
exceptions, while preserving the existing noun/verb convention and previously
documented exceptions.
Breaking change to the
mincommand surface. Second slice of the<noun> <verb>sweep started by #976, which did themip packagehalf.Old → new
min activatemin session activatemin attachmin session attachmin destroymin session destroymin renamemin session renamemin session policy(unchanged, already noun-first)Unchanged by deliberate decision, and commented in the source as exceptions so
a later reader does not "fix" them:
minwith no subcommand — resolve-or-activate-and-attach, the most commonthing anyone does with the CLI
min ls— the highest-traffic command; the break is not worth the consistencymin stop— acts on the daemon backend rather than any session, and is thedaemon-lifecycle command people reach for
min init,min add,min update— passthroughs to themipcommands ofthe same name; keeping the spelling identical across the two CLIs beats the
hierarchy
Nouns accept singular and plural as a visible alias:
session/sessions,loadout/loadouts.The convention is written down
docs/reference/cli.mdgains a Command naming convention section: the<noun> <verb>rule, singular/plural aliasing, verbs shared across nounsrather than owned by one, and a table of the documented exceptions above. This
is the part that stops the convention being re-derived from the command tree
every time someone adds a command.
Verification
just ci(darwin scope)just e2e(VM-backed session e2e over HVF)min ls, sandbox proof (pty attach +min add jq+ run)cargo build -p minimalcargo clippy -p minimalsandbox2dead-code findings are pre-existing on darwin — identical on cleanmain)just e2eis the check that matters here:scripts/session-e2e.shdrives therenamed commands for real, so it proves the re-parenting end to end.
Not verifiable on macOS, left to CI: the
crates/minimaldcall-site updates(the crate does not build on darwin).
Callers swept
scripts/session-e2e.sh,scripts/bulk-upload-e2e.sh,scripts/stress-session-e2e.sh,scripts/e2e-attach-pty.py,scripts/kernel-bump-review.sh,justfile,crates/mctx,crates/minimald,crates/op,crates/sessions,AGENTS.md,README.md, and the docs tree.Out of scope
minimal.toml(sandboxvssessionvs
task) — still undecided, and it gates the shape of the run path.Note for reviewers
An earlier revision of this branch introduced a
providernoun, makingmin provider stopthe long form withmin stopas a shortcut. That has beendropped:
stopstays a plain top-level command. There is noprovidernoun.Refs: #1005
🤖 Generated with Claude Code
Note
Re-parent session verbs under
min sessionnoun in the CLIactivate,attach,destroy,rename,policy) are moved from top-levelmin <verb>tomin session <verb>(withsessionsas a visible alias);lsandstopremain at the top level.min session ...forms.min activate,min attach, etc.) are no longer recognized; callers must use the newmin session <verb>form.Macroscope summarized f79f504.
Summary by CodeRabbit
min session ...format (activate, attach, rename, destroy), with corresponding help and error guidance updated when session arguments are omitted or ambiguous.min session activate/min session attacheverywhere, plus added CLI command naming convention documentation and clarified top-level exceptions.min session ...command wording.