codsh

Site · Gallery · npm · English | 中文

npm: codsh-cli · command: codsh

codsh is an autonomous terminal coding agent for DeepSeek — and any OpenAI-compatible endpoint — built directly on the DeepSeek Harness (dsh). Not a fork.

Its flagship feature, /ship, turns a one-sentence idea into fully verified code through an autonomous 7-stage engineering pipeline, with a built-in live task flow panorama across terminal and browser.

Want to see what it builds? Visit the gallery for real projects, screenshots, and playable results. Every project was built from a one-sentence request, with just one round of interaction and the recommended answer selected for every question.

Install

npm install -g @deepseek-ai/dsh codsh-cli
export DEEPSEEK_API_KEY="your-api-key"
codsh

Common flags:

• codsh -p "task" — Run a non-interactive task directly
• codsh --continue — Continue the last session
• codsh --resume <id> — Resume a specific session
• codsh update — Update launcher and profile runtime

/ship: One Sentence to Verified Code

/ship let long diffs open in a pager instead of scrolling past

/ship automates the complete engineering workflow from idea to delivery:

1. Pre-flight — Checks git working tree state and creates an isolated ship/<slug> branch.
2. Wayfinder — Clarifies core goals, constraints, and trade-offs.
3. Grill — Interactive design interview with smart, recommended defaults.
4. Spec (Gate 1) — Formulates user stories, public seams, and explicit Out of Scope boundaries.
5. Tickets (Gate 2) — Decomposes work into vertical slices structured as an explicit dependency DAG.
6. Landing — Dispatches tickets into parallel Git worktrees for TDD implementation and continuous integration.
7. Done — Verifies acceptance criteria, ensures zero repo regressions, and merges back cleanly.

Live Task Flow Panorama

• Live TTY Teaser: Pinned status row showing real-time ticket counts (待认领 n · 已认领 n · 已关闭 n), in-flight parallel landing worktrees, and the Web flowchart URL.
• ASCII DAG Overlay (Ctrl+G): Instant fullscreen terminal visualization of task dependencies and claim states.
• Local Web Flowchart: Interactive React Flow map (127.0.0.1:<port>) with decision context, recorded Q&As, and landing tickets.

Autonomous Resilience

• Automated Conflict Resolution: Git merge conflicts (including lockfiles and renames) are autonomously resolved by agent sub-tasks with validation retries.
• Pause & Resume: Ctrl+C safely pauses coordination; running a bare /ship resumes unfinished work from where it left off.

The surface

Designed for high-efficiency, keyboard-driven terminal development:

• Clean Terminal UI: Full-screen alternate buffer; input stays pinned at the bottom; restores your shell cleanly on exit.
• DeepSeek Blue Themes: /theme opens a picker that previews each theme live (arrows preview, Enter saves, Esc reverts); /theme <name> switches directly. auto (default) follows the terminal's light or dark background with deepseek / deepseek-light; terminal paints only your terminal's own sixteen colours, with no backgrounds. The choice is saved in $DSH_HOME/code-cli-ui.json; CODSH_THEME=<name> overrides it for one launch.
• Foldable Reasoning: Streaming thoughts collapse into a single line (Ctrl+O or click to expand/collapse).
• Subagent Matrix: Background and parallel subagents run in isolated views (Ctrl+H to list, click/enter to inspect, Esc to return).
• Timeline Navigation: Jump between dialogue turns (Shift+←/→, /jump) or branch off from an earlier turn (/rewind).
• Shortcuts & Controls:
  • Shift+Tab: Toggle plan mode
  • Ctrl+Q: Queue input while the agent is running
  • Ctrl+C: Interrupt current execution
  • Ctrl+V: Paste images directly from clipboard
  • /view, /diff, /copy: Inspect files, uncommitted changes, or code blocks in a dedicated pager

Third-party endpoints

Connect to any OpenAI-compatible gateway in $DSH_HOME/settings.yaml (default ~/.dsh/settings.yaml):

llm-pi-ai:
  providers:
    acme-gateway:
      displayName: Acme Gateway
      apiKeyEnv: ACME_GATEWAY_API_KEY
      api: openai-completions
      baseURL: https://gateway.acme.example/v1
      compat:
        thinkingFormat: deepseek
        supportsDeveloperRole: false
        maxTokensField: max_tokens
      models:
        - id: acme-large
          contextWindow: 65536
          maxTokens: 4096

Switch and persist default model:

/model acme-gateway/acme-large

API keys resolve in order: specified environment variable → $DSH_HOME/.credentials.yaml → <cwd>/.env → $DSH_HOME/.env.

How it works

codsh is a zero-dependency launcher that finds your local dsh, registers codsh-bundle into a code profile, and boots dsh --profile code.

To run directly via dsh:

dsh plugin --profile code add codsh-bundle
dsh --profile code

Terminals

Supports Kitty keyboard protocol, focus reporting, OSC 11 color detection (picks the light or dark theme), OSC 12 cursor color (the theme's accent, restored on exit), and terminal image rendering where available.

Development

See CONTRIBUTING.md.

pnpm run dev          # Start local development surface
pnpm test             # Run unit tests
pnpm run typecheck    # TypeScript typecheck
pnpm run test:e2e     # Run E2E tests

Feedback

Bugs, feature requests, or migrating from Claude Code / Cursor? Open an issue or join the Discussions.

License

MIT