Run one-off tasks with Headless

Headless is a one-off task entry point, not an interactive chat interface. It creates a persistent agent and session, submits one task, waits for the agent to settle and the session to flush, then prints the final non-empty assistant message to the terminal.

Shortest command

With the CLI installed:

dsh --profile headless "summarize this workspace"

From a source checkout:

pnpm run build
pnpm dsh --profile headless "summarize this workspace"

The task cannot be empty. Multiple positional arguments are joined into the complete task.

Output and exit behavior

• A final turn/end reason of completed returns exit code 0.
• Other end reasons return exit code 1.
• Successful runs leave stderr empty.
• A missing or whitespace-only task is a usage error.

Headless does not mount the host, HTTP server, Web runtime, or browser client, and it does not open a listening port. It still has the file, shell, and other tool permissions supplied by its profile.

DSH101 independent run record

On 2026-08-14, DSH101 ran a read-only Headless acceptance check against local source with DSH 0.1.0-rc.5. The command returned an accurate repository summary, exited with code 0, and made no file changes. The API key was neither printed nor written into the test record.

This result is specific to the recorded machine and version. It cannot guarantee success on another system, network, model, or task.

When it fits

Headless fits one-off repository summaries, report generation, controlled batch work, and CI smoke tests. The current entry point creates a new session for each run and does not support interactive follow-up. For programmatic control, permission callbacks, or multi-turn protocols, use the Python SDK or the ACP example instead.