You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 5f8ca29
Browse filesBrowse the repository at this point in the historyBrowse files
docs: streamline READMEs, highlight panorama, and heal stale profile store
- Optimize bilingual READMEs and CLI docs to focus on /ship pipeline, live panorama, and key surface shortcuts
- Drop and reinstall code profile modules when linked from a different pnpm store
- Point homepage Get started button to user guide and document the task flow panorama across site pages
When `codsh update` (or the next start) cannot register `codsh-bundle` because the code profile's `node_modules` were linked from a different pnpm store, drop those modules and retry. A leftover install from another pnpm major used to leave the launcher upgraded and the profile behind.
**`/ship`**takes one sentence to verified code. A terminal coding agent for DeepSeek — and any OpenAI-compatible endpoint.
25
+
**codsh**is an autonomous terminal coding agent for DeepSeek — and any OpenAI-compatible endpoint — built directly on the [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (dsh). Not a fork.
26
26
27
-
A coding profile and a terminal of its own, on [dsh](https://github.com/deepseek-ai/deepseek-harness). Not a fork. For people who want DeepSeek (or their own gateway) instead of a closed agent.
27
+
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.
28
28
29
-
Want to see what it can build? [Visit the gallery](https://blackman99.github.io/codsh/gallery.html) for original requests, real screenshots, and playable projects. Every project was built from a one-sentence request, with just one round of interaction and the recommended answer selected for every question.
29
+
Want to see what it builds? [Visit the gallery](https://blackman99.github.io/codsh/gallery.html) 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**.
2.**Wayfinder** — name the destination and settle open decisions
54
-
3.**Grill** — design-tree interview, with recommended answers
55
-
4.**Spec (Gate 1)** — stories, public seams, Out of Scope; original wording kept
56
-
5.**Tickets (Gate 2)** — vertical slices, a DAG, acceptance checklists
57
-
6.**Landing** — TDD in parallel worktrees; merge and prove
58
-
7.**Done** — acceptance plus no new repo failures; merge back
59
-
60
-
You answer; the same `/ship` continues. `/goal` stays disarmed. While work is in progress, a panorama stays available: TTY overlay (`Ctrl+G` or the teaser), a one-line ticket count with the local Web flowchart URL on that row, and the flowchart itself — `/ship` does not open a browser.
53
+
`/ship` automates the complete engineering workflow from idea to delivery:
61
54
62
-
After verified delivery, the terminal clears the ship phase, ticket counts, plan, old todo readout, and settled subagent readout. Running children remain visible; `Ctrl+T` / `Ctrl+H` still open retained history, and the Web flowchart keeps the final graph. Interrupted or blocked work keeps its progress visible for resuming.
55
+
1.**Pre-flight** — Checks git working tree state and creates an isolated `ship/<slug>` branch.
56
+
2.**Wayfinder** — Clarifies core goals, constraints, and trade-offs.
57
+
3.**Grill** — Interactive design interview with smart, recommended defaults.
58
+
4.**Spec (Gate 1)** — Formulates user stories, public seams, and explicit Out of Scope boundaries.
59
+
5.**Tickets (Gate 2)** — Decomposes work into vertical slices structured as an explicit dependency DAG.
60
+
6.**Landing** — Dispatches tickets into parallel Git worktrees for TDD implementation and continuous integration.
61
+
7.**Done** — Verifies acceptance criteria, ensures zero repo regressions, and merges back cleanly.
63
62
64
-
Grill: ↑/↓ focus · Space toggles multi-select · Enter submits · ←/→ revisit · Esc closes the rest of the round.
63
+
### Live Task Flow Panorama
64
+
-**Live TTY Teaser**: Pinned status row showing real-time ticket counts (`待认领 n · 已认领 n · 已关闭 n`), in-flight parallel landing worktrees, and the Web flowchart URL.
65
+
-**ASCII DAG Overlay (`Ctrl+G`)**: Instant fullscreen terminal visualization of task dependencies and claim states.
66
+
-**Local Web Flowchart**: Interactive React Flow map (`127.0.0.1:<port>`) with decision context, recorded Q&As, and landing tickets.
65
67
66
-
A dirty tree or an unrelated `/goal` asks first. Bare `/ship` resumes unfinished work. Ctrl-C stops coordination.
67
-
68
-
Merge conflicts go to an agent automatically, including lockfile and modify/delete conflicts. It preserves both sides’ intent, retries validation failures up to three attempts, then continues landing and verification. Sealed-requirement conflicts or exhausted retries keep a recovery snapshot and report the specific blocker.
69
-
70
-
The [gallery](https://blackman99.github.io/codsh/gallery.html) pairs original one-sentence requests with screenshots and playable results. Words for the workflow live in [CONTEXT.md](CONTEXT.md).
71
-
72
-
## How it works
73
-
74
-
`codsh` finds your dsh, registers [`codsh-bundle`](https://www.npmjs.com/package/codsh-bundle) into a `code` profile, and boots `dsh --profile code`.
75
-
76
-
A session says so when a newer codsh is out. `codsh update` from the shell, `/update` from inside; both move the profile runtime too. `CODSH_UPDATE_CHECK=off` silences the automatic check.
77
-
78
-
Skip the launcher:
79
-
80
-
```sh
81
-
dsh plugin --profile code add codsh-bundle
82
-
dsh --profile code
83
-
```
84
-
85
-
Any OpenAI-compatible endpoint is a dsh route — declare it once, then `/model`.
68
+
### Autonomous Resilience
69
+
-**Automated Conflict Resolution**: Git merge conflicts (including lockfiles and renames) are autonomously resolved by agent sub-tasks with validation retries.
70
+
-**Pause & Resume**: `Ctrl+C` safely pauses coordination; running a bare `/ship` resumes unfinished work from where it left off.
86
71
87
72
## The surface
88
73
89
-
The [guide](https://blackman99.github.io/codsh/guide.html#see) includes real terminal captures. In brief:
74
+
Designed for high-efficiency, keyboard-driven terminal development:
90
75
91
-
- Alternate screen; the box stays at the bottom; quit gives the shell back.
92
-
- The prompt you just sent pins at the top; its reply fills below. A right-hand timeline jumps turns (`Shift+←/→`, `/jump`). `/rewind` forks from a turn; the original stays in `/resume`.
93
-
- Thinking streams and lands folded in a single row (`Ctrl+O` or click to expand). Each tool call is one row (`✔` / `✗`); the success bullet is dim, consecutive rows have a blank between them, and output is behind the row.
94
-
- A running in-process child is a view (`click to enter`; Esc pops). `Ctrl+H` lists the session's children.
95
-
-`/view`, `/copy`, `/diff` — answers, code blocks, uncommitted changes, in the same reader.
96
-
-`/` commands, `$` skills, `!` shell, `@` files. `⇧Tab` is plan mode. Type while it works to queue (`Ctrl+Q`); Ctrl-C interrupts.
97
-
-`Ctrl+V` pastes images. `/thinking` (alias `/effort`) sets deliberation. Status shows context left. Drag copies in the transcript, the box, and the chrome under it. Away from the window, a waiting decision rings and notifies.
98
-
- Approvals name the call; the third answer remembers a prefix in `.dsh/permissions.local.json`.
99
-
100
-
Off a TTY it is a line reader: no widgets, no drawing.
101
-
102
-
## Terminals
103
-
104
-
| Tier | Terminals | Meaning |
105
-
|---|---|---|
106
-
| First | iTerm2, Terminal.app, VS Code integrated terminal, tmux, Windows Terminal + WSL | a regression here blocks a release |
107
-
| Second | Ghostty, kitty, Alacritty, Warp | a regression here is a bug, not a blocker |
108
-
| Best-effort | native Windows (pwsh) | persistent terminals are unavailable there; the rest is expected to work |
109
-
110
-
Kitty keyboard protocol, focus reports, OSC 11, and inline graphics take effect where the terminal answers; elsewhere the legacy path stays. Ctrl+Enter steering needs the kitty protocol; the queue panel's `s` does the same without it.
76
+
-**Clean Terminal UI**: Full-screen alternate buffer; input stays pinned at the bottom; restores your shell cleanly on exit.
77
+
-**Foldable Reasoning**: Streaming thoughts collapse into a single line (`Ctrl+O` or click to expand/collapse).
78
+
-**Subagent Matrix**: Background and parallel subagents run in isolated views (`Ctrl+H` to list, click/enter to inspect, `Esc` to return).
79
+
-**Timeline Navigation**: Jump between dialogue turns (`Shift+←/→`, `/jump`) or branch off from an earlier turn (`/rewind`).
80
+
-**Shortcuts & Controls**:
81
+
-`Shift+Tab`: Toggle plan mode
82
+
-`Ctrl+Q`: Queue input while the agent is running
83
+
-`Ctrl+C`: Interrupt current execution
84
+
-`Ctrl+V`: Paste images directly from clipboard
85
+
-`/view`, `/diff`, `/copy`: Inspect files, uncommitted changes, or code blocks in a dedicated pager
111
86
112
87
## Third-party endpoints
113
88
114
-
Declare the route once in `$DSH_HOME/settings.yaml` (default `~/.dsh/settings.yaml`), then pick it with `/model`:
89
+
Connect to any OpenAI-compatible gateway in `$DSH_HOME/settings.yaml` (default `~/.dsh/settings.yaml`):
115
90
116
91
```yaml
117
92
llm-pi-ai:
@@ -122,25 +97,57 @@ llm-pi-ai:
122
97
api: openai-completions
123
98
baseURL: https://gateway.acme.example/v1
124
99
compat:
125
-
thinkingFormat: deepseek# how a thinking level travels on the wire
126
-
supportsDeveloperRole: false# system prompt as `system`, not `developer`
100
+
thinkingFormat: deepseek
101
+
supportsDeveloperRole: false
127
102
maxTokensField: max_tokens
128
103
models:
129
104
- id: acme-large
130
105
contextWindow: 65536
131
106
maxTokens: 4096
132
107
```
133
108
134
-
`/model acme-gateway/acme-large` switches to it and saves it as the default. The key resolves per request from the named environment variable, then `$DSH_HOME/.credentials.yaml`, then `<cwd>/.env`, then `$DSH_HOME/.env`. Compat switches and per-model `reasoningEfforts` are in the `@deepseek-ai/dsh-llm-pi-ai` README.
109
+
Switch and persist default model:
110
+
```sh
111
+
/model acme-gateway/acme-large
112
+
```
113
+
114
+
API keys resolve in order: specified environment variable → `$DSH_HOME/.credentials.yaml` → `<cwd>/.env` → `$DSH_HOME/.env`.
115
+
116
+
## How it works
117
+
118
+
`codsh` is a zero-dependency launcher that finds your local `dsh`, registers [`codsh-bundle`](https://www.npmjs.com/package/codsh-bundle) into a `code` profile, and boots `dsh --profile code`.
119
+
120
+
To run directly via dsh:
121
+
```sh
122
+
dsh plugin --profile code add codsh-bundle
123
+
dsh --profile code
124
+
```
125
+
126
+
## Terminals
127
+
128
+
| Tier | Terminals | Support Level |
129
+
|---|---|---|
130
+
| First-class | iTerm2, Terminal.app, VS Code, tmux, Windows Terminal + WSL | Release-blocking compatibility |
Supports Kitty keyboard protocol, focus reporting, OSC 11 color detection, and terminal image rendering where available.
135
135
136
136
## Development
137
137
138
-
See [CONTRIBUTING.md](CONTRIBUTING.md). `pnpm run dev` · `pnpm test` · `pnpm run typecheck` · `pnpm run test:e2e`. This repo never forks the harness (`pnpm run sync:dsh`).
138
+
See [CONTRIBUTING.md](CONTRIBUTING.md).
139
+
140
+
```sh
141
+
pnpm run dev # Start local development surface
142
+
pnpm test# Run unit tests
143
+
pnpm run typecheck # TypeScript typecheck
144
+
pnpm run test:e2e # Run E2E tests
145
+
```
139
146
140
-
## Talk to it
147
+
## Feedback
141
148
142
-
Bugs, Windows, other models, “I came from Claude Code” — open an [issue](https://github.com/Blackman99/codsh/issues). [Discussions](https://github.com/Blackman99/codsh/discussions) are on for longer threads.
149
+
Bugs, feature requests, or migrating from Claude Code / Cursor? Open an [issue](https://github.com/Blackman99/codsh/issues) or join the [Discussions](https://github.com/Blackman99/codsh/discussions).
0 commit comments