Codex DSH Buddy

Use DeepSeek Harness from Codex — Codex decides how to compose and use it.

简体中文 ·

Codex DSH Buddy gives Codex an on-demand DeepSeek Harness execution path. You keep talking to Codex. Codex decides when DSH helps, inspects the available runtime, creates a small internal composition manifest, resolves the required capabilities, starts an isolated official headless agent, and verifies its result.

Direct:  User → Codex → Answer

Buddy:   User → Codex → Manifest → Capability Resolver
                                  ↓
                    builtin / install / develop
                                  ↓
                         isolated DSH Agent
                                  ↓
                           Result → Codex

The core is one Codex Skill and one small MCP/CLI control plane. It adds no planner model, agent loop, plugin marketplace, or DSH runtime. The manifest stays replayable and auditable without becoming part of the user-facing workflow.

Install

Codex DSH Buddy requires Codex CLI and Node.js 22.19+. The official DSH headless runtime is included as a package dependency.

npx -y codex-dsh-buddy@0.1.0 install \
  --source codex-dsh-buddy@0.1.0

Pinned source installation is also supported:

npx -y github:dangoZhang/codex-dsh-buddy#v0.1.0 install \
  --source github:dangoZhang/codex-dsh-buddy#v0.1.0

Restart Codex. The installer copies the codex-dsh-buddy Skill to ~/.agents/skills, registers the MCP server, and gives long DSH runs a bounded MCP timeout. It never edits a DSH profile or pre-approves execution; Codex keeps its normal approval flow for dsh_composition_run.

Then talk to Codex normally. It can choose DSH when the task benefits from it, or you can ask explicitly:

Use DeepSeek Harness to investigate this repository and report the failing test.

Controller workflow

Codex owns every planning and review decision:

1. Inspect the current official headless composition.
2. Generate an internal dsh.compose/v1alpha1 manifest for the task.
3. Dry-run capability, plugin, patch, conflict, and security resolution.
4. Reuse a builtin or installed plugin; inspect a community candidate; develop a minimal local plugin only when nothing fits.
5. Resolve again, run one isolated DSH agent, and wait for completion.
6. Check the final answer, session, trace summary, and artifacts before reporting to the user.

The MCP server makes no LLM call. Its complete model-facing API is:

dsh_composition_inspect()
dsh_composition_resolve(manifest)
dsh_composition_run(manifest, task)
dsh_composition_save(manifest, name?)

The same control plane is available from the terminal:

codex-dsh-buddy inspect
codex-dsh-buddy resolve examples/demo-existing-capability.yaml
codex-dsh-buddy run examples/demo-existing-capability.yaml --task "Summarize package.json"

Composition manifest

The versioned manifest maps directly to DSH profile, patch, model, tool, sandbox, and persistence settings. Users do not need to author it.

apiVersion: dsh.compose/v1alpha1
kind: AgentComposition
metadata:
  name: repo-investigator
workspace:
  cwd: /absolute/path/to/repo
base:
  profile: headless
capabilities:
  - id: filesystem
    reason: Inspect repository files
  - id: code-execution
    reason: Run the requested checks
agent:
  persona: Investigate the task and return evidence.
sandbox:
  mode: workspace-write
run:
  timeoutMs: 300000

Selected plugins record an exact source, provided capability IDs, review decision, and provenance. GitHub plugins must be commit-pinned. Local plugins enter the isolated profile as file: snapshots.

Capability resolution

Resolution always follows one order:

builtin / current runtime
  → installed plugin
  → inspected community plugin
  → unresolved: recommend develop-plugin + extension seam

Community discovery follows the conventions established by deepseek-harness-plugin-mcp. If a capability remains unresolved, the control plane returns a recommendation such as develop-plugin and tool | provider | guard; Codex or dsh-plugin-builder creates the code, then adds its reviewed local path to the manifest and resolves again.

Isolation and audit

Every run receives a fresh DSH_HOME, the official headless profile, a generated --patch overlay, and a run-local JSONL session root. Existing DSH settings and web profiles are never copied or overwritten.

State defaults to ~/.codex-dsh-buddy; set CODEX_DSH_BUDDY_HOME to move it. Each run records:

runs/<run-id>/
  manifest.yaml
  resolved-manifest.yaml
  cordis.patch.yml
  resolution.json
  run.json
  artifacts.json
  trace/
    summary.json
    stdout.txt
    stderr.txt
    sessions/.../session.jsonl

Codex receives the normalized answer and trace summary. The raw trace remains available by path for audit and replay.

Contributing

Keep the manifest small, map features to public DSH composition APIs, and preserve Codex as the only planner.

pnpm install
pnpm check
pnpm test:real

License

MIT © Codex DSH Buddy contributors