ACP (Agent Client Protocol)¶
Alpha — The
--acpmode is functional and actively developed, but the exact set of ACP v1 methods and session updates janito emits may change between releases. Pin a specific version if you depend on it.
Janito can run as an Agent Client Protocol (ACP) v1 agent: a subprocess that editors and AI-native development tools spawn and talk to over stdin/stdout using newline-delimited JSON-RPC 2.0. This lets the editor drive janito — sessions rooted in your project directory, prompts that render into the editor's chat UI, tool calls shown as progress cards, and cancellation of a running turn — instead of you switching to a terminal.
The ACP agent reuses the same headless agentic loop as --web
(janito.web.backend.agent), so the tools, MCP services, skills, privileges,
and configuration are identical to the other surfaces.
Running as an ACP agent¶
Launch janito from the editor's agent configuration:
ACP runs must speak JSON-RPC, so janito does not accept a chat prompt in this mode. Configure the provider, model, and API key the same way you would for any other use:
janito --set provider=openai --set model=gpt-6-luna
janito --set-api-key="sk-your-key" --provider openai
Protocol surface¶
- Transports — stdio only. Requests arrive line-by-line on stdin; responses
and
session/updatenotifications go to stdout. stdout carries only ACP messages — the version banner, plugin loading output, and all other logs are redirected to stderr so the stream stays valid JSON. - Methods —
initialize,session/new,session/prompt, and thesession/cancelnotification. Other v1 methods (session/load,session/list,session/delete,authenticate, ...) are not implemented and answer with-32601 Method not found. - Initialization — janito negotiates protocol version 1 and reports
promptCapabilities.embeddedContext = true(resource blocks are accepted), no image/audio input, and no client-side MCP servers. - Sessions —
session/newrequires an absolutecwd; all file-relative work happens inside that directory for the lifetime of the session. The system prompt (custom-S, effective default prompt including the sessioncwd'sAGENTS.md) is resolved under the requestedcwdand prepended to the conversation.session/newwaits for any active turn instead of racing itschdir. - Prompt content —
textblocks are sent verbatim;resourceblocks (with file contents) andresource_linkblocks are converted into the prompt. Image and audio blocks are passed through as a note that they were ignored (janito has no vision/audio input). - Streaming — token text maps to
agent_message_chunk, reasoning toagent_thought_chunk, tool calls totool_call/tool_call_update(withkind, human-readabletitle, and filelocationsresolved against the session'scwd). A turn ends with eitherstopReason: "end_turn"orstopReason: "cancelled". - Cancellation —
session/cancelcancels the running turn; the prompt request then resolves withstopReason: "cancelled"instead of an error. Cancellation stops streaming promptly but waits for the current sync work (tool execution, MCP discovery, sync SDK chunks) to finish before restoring the sessioncwd; repeated cancels never interrupt that cleanup. A cancelled turn, a failed turn, and a turn ending in an error event all roll the conversation back to before the turn, preserving the system prompt and earlier completed turns. - One turn per session — a second
session/prompton a session with a running turn is rejected (-32602) instead of interleaving with it.
Known limitations¶
-
Synchronous work cannot be forcibly stopped. Cancellation and stdin shutdown wait for an in-flight tool, MCP discovery, or sync SDK chunk to finish. Turns and session creation are serialized while that work owns the process cwd; a long-running tool delays other sessions too.
-
Client
mcpServersare ignored. Janito uses the MCP servers configured in its ownmcp_config(/mcpservices) and does not connect to servers the client proposes, andmcpCapabilitiesare reported as disabled. session/loadis not supported, so sessions are ephemeral in memory and do not persist across agent restarts.- Token usage is not reported (
usageupdates are skipped). Janito's counters do not match the ACP usage-group semantics, so reporting them would mislead clients that render token bars. - Mid-turn user questions via the
AskUsertool are not surfaced to the client (session/request_permissionis not emitted), so the tool is skipped. - Unix-like platforms. The stdio transport relies on
asyncio.connect_read_pipe, which the default Windows event loop does not implement —--acpis currently Linux/macOS only.