Conversation
…tart-session` overrides Adds a dedicated CLI reference page for AI Sessions and cross-links from the surrounding pages: - New `docs/9-ai-sessions/cli.md` covering `ai session list/get/history/terminate`, `ai session attach` (flags, interactive controls, 403 fallback, output format with colour-coded message table), and `ai start-session` with its full override flag set (model, max-turns, max-budget-usd, task-budget-tokens, ttl-seconds, one-shot, permission-mode, allowed/denied-tools, plugin, env, anthropic-key, lc-api-key, lc-uid). - mkdocs.yml nav: add the new Command Line Interface entry under AI Sessions. - user-sessions.md: add a tip box pointing to the CLI attach command alongside the existing WebSocket example. - dr-sessions.md: note at the end of Example 5 that the same `ai_agent` Hive record can be reused as a CLI template via `ai start-session`. - 6-developer-guide/sdk-overview.md: add an AI Sessions section under Commands with the common invocations and a cross-link to the new page. Cross-links: * python-limacharlie: refractionPOINT/python-limacharlie#278 * lc-ai: (see matching PR) Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This was referenced Apr 18, 2026
…fix WS paths Three sets of changes to docs/9-ai-sessions/cli.md and the surrounding pages, matching the additions in refractionPOINT/python-limacharlie#278: * New "Two session ownership models" section near the top of cli.md spelling out the org-vs-user split, since the CLI now has parallel command groups for each (`ai start-session` + `ai session` for org-owned; `ai chat` + `ai chats` for user-owned). * New `ai auth claude {status,login,set-key,logout}`, `ai chat`, and `ai chats {list,get,history,terminate}` sections covering the user-owned interactive chat path. Clarifies that `ai chat` requires a per-user Claude credential (set via `auth claude`) and that `ai chats` is the lifecycle counterpart to `ai session` for user-owned sessions, with sessions of one ownership model being invisible to the other group's commands. * WebSocket URL paths corrected from the legacy `/v1/sessions/{id}/ws` and `/v1/org/sessions/{id}/ws` forms (which are unreachable through the GCP load balancer and return 404) to the new `/v1/ws/sessions/{id}` and `/v1/ws/org/sessions/{id}` forms the LB actually routes to the interaction-proxy. Plus knock-on edits: - "Endpoint selection and fallback" gains a tip box explaining that `--interactive` only sends prompts for user-owned sessions; org sessions transparently fall back to read-only by design. - The start-and-attach example under `ai start-session` no longer passes `--interactive`, since that flag is moot for the org-owned session it just created. - user-sessions.md tip retargeted from `ai session attach --interactive` to `ai chat` (the natural CLI entry point now). - sdk-overview.md AI Sessions section restructured to show both ownership paths side by side with the credential setup step. Cross-links: * python-limacharlie: refractionPOINT/python-limacharlie#278 Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
maximelb
changed the title
limacharlie ai session attach and ai start-session overridesai CLI surface (org + user sessions, attach, chat, auth claude)
…`ai session attach` / `ai chat` Matches refractionPOINT/python-limacharlie@4f1e200, which cleaned up the pretty-printed live stream so `ai chat` is actually readable: - Plumbing `system` subtypes (credential_diagnostics, model_set, hook_started, autoinit_loaded, ttl_added_to_system_prompt, ...), `session_status` startup pings and `usage_delta` frames are hidden by default. - Empty assistant-tool-use-only frames, user tool_result wrappers and summary-less `result` pings are skipped. - Timestamps are abbreviated to `HH:MM:SS`. - A new `--verbose`/`-v` flag on both `ai session attach` and `ai chat` restores the firehose (useful when debugging session startup or correlating with server logs). Changes in docs/9-ai-sessions/cli.md: - Flag tables for `ai session attach` and `ai chat` gain a `--verbose`/`-v` row that cross-links the new "Default noise filter" subsection. - New "Default noise filter" subsection under "Output format" enumerates the filtered types / subtypes / empty-frame rules and calls out that the same set is used by `ai session history` / `ai chats history`. - The existing one-liner under `ai session history` now cross-links the shared filter section so readers see both surfaces share it. - Output-format section notes that timestamps default to `HH:MM:SS` and `--verbose` preserves the full ISO-8601 value. No behavioural change elsewhere — `--raw` semantics, endpoint selection, interactive controls and the colour-coded table are unchanged. Cross-links: * python-limacharlie: refractionPOINT/python-limacharlie@4f1e200 Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
maximelb
added
the
to-code-review
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Documents the AI Sessions CLI surface shipping in python-limacharlie#278. The CLI now spans both ownership models the backend supports — org-owned (automation, started via
ai start-sessionor DR rules) and user-owned (interactive chat, started viaai chat) — so the docs treat both as first-class.docs/9-ai-sessions/cli.md
ai session attach --interactiveactually does for each.ai session list/get/history/terminate,ai session attach,ai start-sessionwith the full override flag surface (model, turns, budgets, ttl, one-shot, permission mode, allow/deny tool lists, plugins, env merge, credential overrides).ai auth claudesection —status,login(browser OAuth flow with code prompt),set-key(literal,hive://secret/, or--key-from-stdin),logout. Documents theErrNoClaudeCredentialsfailure path and the 5-minute OAuth-flow TTL.ai chatsection — opening prompt as PROMPT arg only (stdin reserved for the interactive loop), three-step flow (status → register → create → attach), full flag table, interactive controls cross-link, re-attach guidance.ai chatssection — lifecycle counterpart toai session(list/get/history/terminate) but routed at/v1/sessions/*. Subcommand-by-subcommand parity table; explicit note that the two ownership models' command groups are disjoint./v1/sessions/{id}/wsand/v1/org/sessions/{id}/wsforms to the GCP-LB-routable/v1/ws/sessions/{id}and/v1/ws/org/sessions/{id}forms.--interactiveactually accepts your input (only user-owned sessions; org sessions auto-fall back to read-only by design).ai start-sessionsection drops the now-misleading--interactiveflag.docs/9-ai-sessions/user-sessions.md
ai session attach --interactivetoai chatas the natural one-step CLI entry point for user-owned interactive sessions.docs/6-developer-guide/sdk-overview.md
ai start-session+ai session, user viaai auth claude+ai chat+ai chats), with a short note on--interactive's read-only fallback for org sessions.mkdocs.yml
Cross-linked PRs
Test plan
mkdocs build --strictlocally — verify no broken internal links once mkdocs is installed in the build env.9-ai-sessions/cli.mdpage for formatting (especially the ownership-model table, the new section anchors used by cross-links, and the tip-box rendering).cli.md↔user-sessions,dr-sessions,api-reference,sdk-overview).