Skip to main content

pilot-harness/packages/bundle/headless

240Stars13Forks16Issues1Watchers

DSH one-time task execution bundle: run an Agent directly from the command line and exit, bypassing the web interface and browser.

Categories⌨ Developer Tools
Evidence4/5methodologySourceInstallMaintenanceDSH versionSecurity scan
Machine-auditedInstall commandRepo verifieddsh-plugin topicLicenseREADMEAI wiki

ⓘ This plugin is a sub-package of the op7418/pilot-harness monorepo — stars and activity count the whole repository.

op7418op7418
·op7418/pilot-harness
Language
TypeScript
License
MIT
Branch
main
ai-agentcodepilotdeepseekdeepseek-harnessdesktop-appdshdsh-pluginelectron

Install

cmdweb profile
$ dsh plugin --profile web add @deepseek-ai/dsh-headless

Run the command above in your terminal to install this plugin via the dsh CLI. You can switch Profile in the top-right corner. New to dsh? Read the beginner tutorial

Install via your agent

Install the DeepSeek Harness plugin op7418/pilot-harness/packages/bundle/headless for me: review the repository at https://github.com/op7418/pilot-harness first, then run the install command and verify the plugin loads successfully.

Paste this instruction to the DSH Web GUI assistant — it will install and verify for you.

One-Line Description

A one-shot task bundle for dsh: receives a task text from the command line, runs an Agent, outputs the answer to stdout, and exits—without starting a Web UI or browser.

Core Capabilities

  • Execute tasks from the command line in one shot, without opening a Web UI or browser
  • Automatically create a persistent Agent, submit the command-line task as a user message, and exit once the Agent enters idle state
  • Before exiting, call sessions.flush to persist the session and write the last non-empty Assistant text to stdout
  • Use exit code to indicate results: exit code 0 when the final turn ends with "completed"; exit code 1 for all other cases (including errors, aborts, or empty turns)
  • Does not open any listening ports; pure process-level execution, suitable for CI, scripts, cron jobs, and other automation scenarios
  • Rejects startup if task text is missing, displays usage and exits with non-zero code to avoid empty runs

Technical Implementation

  • Language: TypeScript (ESM, "type": "module")
  • Key Dependencies: @deepseek-ai/cordis (plugin framework), @deepseek-ai/dsh-agent (Agent and Inbox), @deepseek-ai/dsh-session (persistent sessions), commander (CLI parsing)
  • Architecture Pattern: cordis named export function plugins (name/inject/Config/apply), injected along with headless-startup and headless-invariant three same-named plugins into dsh-base via cordis.patch.yml; runner obtains host services (agentDefaultModel, agents, sessions) through Cordis context, then exits via the host-provided appExit hook
  • Entry Files: src/index.ts (runner), src/startup.ts (CLI provider), src/invariant.ts (invariant companion plugin)

Use Cases

This bundle is most suitable when you want to run an AI task directly in CI, scripts, or cron jobs without opening or unable to open the Web console. It only reads command-line arguments, runs an Agent, outputs the answer to stdout, and uses exit codes to indicate success or failure to the caller.

It can also serve as a reference for dsh's minimal usable Agent call stack—one-shot runner + Code Mode worker + base tool stack, sufficient to understand how Cordis plugins drive a complete conversation without mounting Web.

Prerequisites & Compatibility

DependencyMin VersionDescription
DSH0.1.0-rc.7+Depends on packages in the workspace: dsh-base, dsh-agent, dsh-session, dsh-llm, dsh-invariants, dsh-cmdline, dsh-agent-default-model, dsh-code-runtime-worker-thread; all these peerDependencies are declared as workspace:^
Node.js^22.19.0 || >=24.0.0Required by engines field in monorepo root package.json; bundle itself has no separate declaration
PlatformCross-platformAll Node.js process-level logic, no system calls or native bindings
Native ModulesNoneAll dependencies are pure JS/TS, no native dependencies like node-pty, node:sqlite

Installation

dsh plugin --profile web add github:op7418/pilot-harness/packages/bundle/headless

After installation, invoke this bundle via dsh --profile headless "your task".

Configuration

ConfigTypeDescriptionDefault
taskstring (required)Single task text for the Agent to execute; multiple words on command line are concatenated with spacesnone

This field is injected via lazy configuration by the headless-startup plugin in cordis.patch.yml after parsing the command line; the runner itself does not directly accept Cordis configuration.

FAQ

Q: Can the task have multi-turn dialogue?

A: No. The runner only submits the command-line argument as one user message to the Agent, waits for the Agent to complete one turn, then exits. There's no entry point for follow-up questions or continued dialogue.

Q: How to determine success/failure from exit code?

A: Exit code 0 means the final turn ended with "completed"; all other cases (including abort, model error, or no turn occurred) return 1, making it easy for scripts and CI to judge directly.

Q: Where does output go when the answer is irrelevant or model errors occur?

A: The last non-empty Assistant text is written to stdout; model error codes and messages are written to stderr in the format "dsh: CODE: message"; stderr is empty under normal conditions.

Q: What happens if task text is not provided?

A: The launcher rejects it during the parsing phase, displays "a task is required" and exits with code 1. The runner is never activated, and the entire process does not enter the Agent creation flow.

Q: Will any ports be opened?

A: No. This bundle does not mount Host, HTTP server, or Web runtime; the process does not listen on any ports, making it suitable for containerized or restricted network environments.

Q: How to uninstall?

A: Execute dsh plugin --profile web remove github:op7418/pilot-harness/packages/bundle/headless under the profile where you originally installed it.

Q: Does this bundle modify the model system prompt?

A: Yes. Its cordis patch changes the system-prompt persona to "You are a coding agent powered by the {{model}} model" and injects the current working directory into the persona.

Q: Where is data stored?

A: Before exiting, it calls sessions.flush to persist the session to the host-configured Session storage; the specific path is determined by the DSH launcher and Session plugin. This bundle does not create any separate local files.

Difficulty

Beginner — there's only one command to use: dsh --profile headless "your task". No UI, config files, or additional parameters. An ordinary user can copy one line of command and run it.

Known Issues & Limitations

  • Only supports single submission: The runner has no interactive follow-up entry point; after submitting one task, it waits to exit. Multi-turn follow-up is not supported.
  • Depends on host providing ctx.appExit hook: When starting the headless profile in a host environment that doesn't provide this hook, activation will throw "the launcher must provide ctx.appExit before the tree mounts" and fail.
  • Does not mount Web tool stack: No Host, HTTP, Web runtime, or browser plugins; cannot reuse any Web-mode interaction capabilities (such as approvals, file browser, or extension UI).
  • No TODO/FIXME comments found: No unresolved development markers in the source code.

Read the usage guide →

Install steps, key points, FAQ and compatibility for this plugin — auto-derived from indexed fields.

Listing badge

Listed on deepseek-plugin.org
[![Listed on deepseek-plugin.org](https://img.shields.io/badge/listed_on-deepseek--plugin.org-007EC6)](https://deepseek-plugin.org/plugins/op7418/pilot-harness/packages/bundle/headless)

Paste this markdown into your GitHub README to link back to this listing. The badge only states the listing — not a security endorsement.

← Back to plugin directory