AI Coaching via CLI (manage coaching artifacts and start interviews from an AI agent)
AI Coaching via CLI lets an outside AI agent browse the interview-prompt library, list and read saved coaching artifacts and their version history, propose new artifacts, edits and deletions, and start a new interview — over Omniscio's local control server. Covers which routes apply immediately, which wait for inbox approval, and idempotency.
On this page
What it is
Omniscio's AI Coaching virtual project — the structured-interview surface where you answer a sequence of guided questions and walk away with a saved artifact — is reachable from outside Omniscio over the same 127.0.0.1:19519 localhost HTTP server that already exposes cron jobs, automations, recipes, settings, bookmarks, and tags. An external AI agent (Claude Code in another project, ChatGPT with the omniscio-control skill, a curl script) holding the Omniscio bearer token reaches every one of those primitives from a shell.
The in-app surface is described in ai-coaching.md; this page covers the CLI routes that expose those primitives over HTTP.
The gating model is split across the routes by blast radius, identical in shape to the bookmarks and tags CLI surfaces:
- A kill switch covers every route for outside callers. The
aiCoachingCliEnabledsetting (defaulttrue, toggle at Settings → CLI Control → "Enable AI Coaching CLI") short-circuits every route to 403 with{ ok: false, error: "AI Coaching CLI access is turned off. Enable it from the app's CLI Control settings.", disabled: true }before any auth, parse, or rate-limit work. It runs first, so its 403 wins over rate-limit and auth errors. The coach's own key is exempt; turning AI Coaching off still closes it. The switch is read again when a queued interview start is approved: with it off, the approval is refused unless the request was proven to come from the coach's own session. - Artifact and interview mutations are approval-gated.
POST /ai-coaching/artifacts(create),PATCH /ai-coaching/artifacts/:id(update),DELETE /ai-coaching/artifacts/:id(delete with cascade preview) andPOST /ai-coaching/interviews(start an interview) enqueueai_coaching.artifact_create/ai_coaching.artifact_update/ai_coaching.artifact_delete/ai_coaching.start_interviewrows in the sharedcli_pending_actionsqueue. The route returns HTTP 202 at once; nothing applies until the user clicks Approve in the inbox — the same guarantee and open-pending cap as the other approval-gated CLI capabilities in cli-pending-actions.md. The artifact create, update and delete take the full-access key only (in-app keys get 403, agent keys 401)./interviewsalso takes the coach's key; other session keys get 401. - Three destructive routes ask first too.
POST /ai-coaching/interviews/:promptId/reset,DELETE /ai-coaching/goals/:idandDELETE /ai-coaching/memories/:sessionIdqueue an inbox card in the same approval family as the artifact delete. - That consent belongs to the person who gave it. The "ask me before agents change my coaching profile" switch (Settings → CLI Control → AI Coaching profile writes) and any always allow granted on one of those cards are withdrawn when a different account signs in, so the new person is asked on the first write to their own profile. Only that family is withdrawn — other families' switches and grants survive — and signing back in as yourself keeps your own choice.
- Every other mutation applies immediately. Only the seven routes above and the two Core Profile writes enqueue a pending row. Everything else writes straight through with no inbox card:
POST/PATCH/DELETE /ai-coaching/bookmarks(per-session key-moment notes — a quote plus an optional label, injected into the coach's context; a delete erases only that one bookmark and its search copy; these are NOT the/bookmarks/*launcher rows, which are a different feature with their own kill switch),POST /ai-coaching/memories,POST /ai-coaching/goals,PATCH /ai-coaching/goals/:idandPOST /ai-coaching/goals/:id/checkins,PUT /ai-coaching/pinned-context,PATCH /ai-coaching/artifacts/:id/level(except a choice that would let other sessions see a Coaching only write-up, which asks first), andPOST /ai-coaching/custom-interviews.POST /ai-coaching/sessions/:sessionId/artifactis the in-app coach's OWN save path, called with its own session key — session-bound (an agent/in-app token may write only its own session) and title-locked (the title comes from the session, not the body). So the split is NOT "reads are free, everything else is gated"; the settings copy in Settings → CLI Control says the same thing. External agents use the create/update/delete routes above. - Reads are bearer-gated and read-budgeted. All seven GETs require the bearer token and are read-budgeted at 60 reads/minute per SOURCE — keyed on the source session the dispatcher publishes for the request, with the bearer hash used only when the request names no source — under a 600 reads/minute fleet-wide backstop that bounds every source combined. It is not one 60/min bucket shared by every token holder: on a real install every agent presents the same global token, and a single bucket at that key would mean 60 reads/minute for the entire box.
Where to find it
The in-app half of AI Coaching is the sub-sidebar with Dashboard, Sessions, Artifacts, Bookmarks and Archived, plus the artifact editor and its version history. The agent-facing half has no screen at all: an outside AI reaches the same prompts, artifacts and interviews over Omniscio's local control server, with the same access token the rest of the automation surfaces use. Saved artifacts are the part that reaches beyond this feature — they are injected as a "Things to know about the user" profile block when an ordinary session starts, so what is written here shapes how your agents behave later.
How it behaves
Whether a change happens at once or waits for you depends on what it touches. Reading is always safe and free, and an interview session saving its own artifact is locked to that one session and one title so it can simply write; everything else — creating, editing or deleting an artifact, and starting a new interview that spends real Claude time — waits in your inbox until you approve it. When a queued change has stopped making sense by the time you look at it, it is rejected with a reason rather than applied to the wrong thing.
Related
How an interview actually runs — the prompts, the extraction, and the profile block it leaves behind — is covered by AI Coaching and part 2. For the most-asked questions about the feature, see the AI Coaching FAQ.
- ai-coaching.md — the in-app AI Coaching virtual project (sub-sidebar, prompt library, artifact editor with version history, restore / delete UX, profile-block injection on regular session spawns).
- cli-control.md — the CLI server itself, token handling, the full route catalog.
- cli-pending-actions.md — the shared approval queue every approval-gated CLI mutation lands in (cron, automation, settings PATCH, session lifecycle, recipes, tags, bookmarks, AI Coaching).
- cli-tags.md — the tag-library CLI surface that this page's split-gating pattern most closely mirrors.
- bookmarks.md — the bookmarks CLI surface that introduced the per-feature kill-switch pattern this page uses.
- omniscio-control skill — the external-AI side of the contract: how an AI queues these actions in practice.
Last verified 2026-10-16