Sundial Editor CLI

@arcridge/sundial-editor-cli is the bridge between the ArcRidge Sundial Editor interface (such as the Visual Studio Code plugin) and the backing store of files stored in the .sundial directory within the project source. It runs on Node.js 20 or newer and supports a locally authenticated Codex CLI 0.131.0 or newer when that installation passes Sundial's app-server capability probe. Newer Codex versions are not rejected solely because their version differs from the build used to generate earlier protocol schemas.

The sundial editor is an editor plugin the provides ways to interact with agents rooted in teh source; by anchoring conversations, questions, and patches against annotations within the source, and prompting agents to annotate source with aditional contextual information. The CLI is the command surface that provides a management toolset for the plugin to operate; with the added benefit that a power user can also use these commands interactively.

The package installs two executables at the same version:

• sundial-editor-cli is the editor control surface. It manages source annotations, named agents and their queues, sessions, transcripts, and lifecycle controls. Run sundial-editor-cli help for its complete command surface.
• sundial-agent-tools is the intentionally narrow surface described to managed agents. Run sundial-agent-tools help to see the agent-facing surface.

Debugging Codex Integration

Sundial currently is integrated with Codex, and uses the codex tools to maintain and update persistent agent chat sessions.

sundial-editor-cli health --provider codex reports the exact Codex executable path and version resolved from the CLI process's PATH. It initializes app-server, validates model discovery and the required thread/history operations, checks turn RPC recognition with invalid parameters, and archives its temporary probe thread. Successful results are cached for 24 hours in machine-local configuration and invalidated when either the Sundial CLI or Codex version changes; pass --refresh to force a new probe. The probe never starts a model turn. A missing or malformed required capability is reported by RPC name with an update/retry diagnostic.

Sundial queries model/list before starting a thread or turn. An explicit Sundial model request must match the visible catalog and is passed to Codex. Without an explicit request, Sundial omits the model override—even when one catalog row has isDefault: true—so Codex applies its configured model and resumed threads retain their existing model.

High level functions

The sundial editor operates like a bunch of agents (including the engineer) working together as fast as possible in the same changing codebase. The tools that sundail provides help control this chaos. It is not intended to a be a spec-driven development solution (see the ArcRidge sundial plugin for this style workflow) and is instead intended to be a more adhoc and less organized (stream of concsiousness) working style.

The primary mechanism to coordinate this chaos are file annotations, each source file with one ore more active annotations has a companion file mirroring it in the .sundial directory. The CLI provides the editor the mechanism to create, maintain, and repair these annotation as source changes.

Additionally, agents are promted to use the sundial-agent-tools CLI to update the status of tasks.

Agents (and the engineer) can inspect each other's plans

Managed agents inspect each other's current coordination state and structured file claims with coordination list, then publish working, waiting, blocked, or paused updates with coordination update. They publish assignment progress with provide-status-update.

Code-centric workflows

Agents may write optional Markdown code annotations against any useful workspace file and line with annotate.

Small task focus

To finish an assignment, the agent writes its complete Markdown answer to the announced .sundial/<UserTurnId>response.md handoff and invokes record-task-response with that exact one path. The command durably appends the official response to its originating conversation turn, completes that turn's assigned work, consumes the handoff, and returns only the normalized source path. Ordinary provider output is not treated as an official response.

The CLI offers tools to maintain a work queue for each agent (the user specifically targets agents with specific tasks).

Named agents, queued work, replaceable sessions, ordered status histories, and per-session coordination histories persist separately under .sundial/agents/. This runtime directory is CLI-owned and gitignored; it is not part of the checked-in annotation companions.