dgf1988/codewhale
1
0
Fork 0
Code Issues Pull Requests Actions 2 Packages Projects Releases Wiki Activity

docs: clean up README, remove roadmap.md

Browse Source 
- Rewrite README to be concise and user-focused
- Replace verbose tool inventory with capability summary
- Move Runtime API details to docs link
- Trim troubleshooting, config, and keyboard shortcuts
- Remove roadmap.md
This commit is contained in:
Hunter Bown
2026-02-16 12:24:01 -06:00
parent 5f90e1685e
commit ccefab8d44
2 changed files with 59 additions and 200 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+59 -187
View File
@@ -13,8 +13,6 @@ Chat with DeepSeek models directly from your terminal. The assistant can read an
### 1. Install
Choose one of:
```bash
# From crates.io (requires Rust 1.85+)
cargo install deepseek-tui --locked
@@ -23,255 +21,129 @@ cargo install deepseek-tui --locked
git clone https://github.com/Hmbown/DeepSeek-TUI.git
cd DeepSeek-TUI
cargo install --path . --locked
# installs `deepseek` to ~/.cargo/bin (ensure it is on your PATH)
```
Prebuilt binaries are also available on [GitHub Releases](https://github.com/Hmbown/DeepSeek-TUI/releases).
### 2. Set your API key
Get a key from [platform.deepseek.com](https://platform.deepseek.com), then:
On first run, the TUI can prompt for your API key and save it to `~/.deepseek/config.toml`. You can also create the file manually:
Get a key from [platform.deepseek.com](https://platform.deepseek.com). On first run the TUI will prompt you to enter and save it, or create the config manually:
```toml
# ~/.deepseek/config.toml
api_key = "YOUR_DEEPSEEK_API_KEY" # must be non‑empty
default_text_model = "deepseek-v3.2" # optional
allow_shell = false # optional
max_subagents = 3 # optional (1‑20)
api_key = "YOUR_DEEPSEEK_API_KEY"
```
Alternatively, run `deepseek` and the onboarding wizard will prompt you to enter and save the key.
### 3. Run
```bash
deepseek
```
On first launch the TUI opens in **Agent** mode. Press **Tab** to switch modes, **F1** or type `/help` to see all commands, and **Esc** to cancel a running request.
### 4. Optional setup
```bash
# Bootstrap MCP server config and skills templates
deepseek setup
# Verify your environment
deepseek doctor
```
## Keyboard Shortcuts
| Key | Action |
|-----|--------|
| `Enter` | Send message |
| `Alt+Enter` / `Ctrl+J` | Insert newline |
| `Tab` | Autocomplete slash command (or cycle modes) |
| `Esc` | Cancel request / clear input |
| `Ctrl+C` | Cancel request or exit |
| `Ctrl+K` | Open command palette |
| `Ctrl+R` | Search past sessions |
| `F1` or `Ctrl+/` | Toggle help overlay |
| `PageUp` / `PageDown` | Scroll transcript |
| `Alt+Up` / `Alt+Down` | Scroll transcript (small) |
| `l` (empty input) | Open last message in pager |
| `v` (empty input) | Open selected/latest tool details |
Press **Tab** to switch modes, **F1** for help, and **Esc** to cancel a running request.
## Modes
Press `Tab` to cycle modes: **Plan -> Agent -> YOLO -> Plan**.
| Mode | Description | Approvals |
|------|-------------|-----------|
| **Plan** | Design-first prompting; produces a plan before implementing | Manual for writes and shell |
| **Agent** | Multi-step autonomous tool use | Auto-approve file writes, manual for shell |
| **YOLO** | Full auto-approve (use with caution) | All tools auto-approved |
Normal mode is also available (chat-only with manual approval for everything) and can be selected via `Esc` from Agent mode or `/set mode normal`.
Press `Tab` to cycle modes. Normal mode (manual approval for everything) is also available via `/set mode normal`.
Override approval behavior at runtime: `/set approval_mode auto|suggest|never`.
## What It Can Do
## Tools
The assistant has access to 30+ tools:
The model has access to 30+ tools across these categories:
- **File operations** — read, write, edit, patch, search, and grep across your workspace
- **Shell execution** — run commands with timeout, background execution, and interactive I/O
- **Web browsing** — search the web, open pages, screenshot, and extract content with citations
- **Git** — inspect repo status, diffs, and staged changes
- **Code review** — structured review for files, diffs, or GitHub PRs
- **Sub-agents** — spawn background agents or coordinate agent swarms for parallel work
- **Task management** — to-do lists, implementation plans, persistent notes, and a background task queue
- **Structured data** — weather, finance, sports scores, time zones, and a calculator
- **MCP integration** — connect external tool servers via the [Model Context Protocol](docs/MCP.md)
### File Operations
- `list_dir` / `read_file` / `write_file` / `edit_file` — basic file I/O within the workspace
- `apply_patch` — apply unified diffs with fuzzy matching
- `grep_files` / `file_search` — search files by regex or name
- `git_status` / `git_diff` — inspect repository status and changes
### Shell Execution
- `exec_shell` — run commands with timeout support and background execution
- `exec_shell_wait` / `exec_wait`, `exec_shell_interact` / `exec_interact` — wait on or send input to running commands
### Web & Browsing
- `web.run` — multi-command browser (search / open / click / find / screenshot / image_query) with citation support. Note: the tool name is `web.run` (single dot), not `web..run`.
- `web_search` — quick DuckDuckGo search when citations are not needed
### Task & Project Management
- `todo_write` — create and track task lists with status
- `update_plan` — structured implementation plans
- `note` — persistent cross-session notes
- `/task add|list|show|cancel` — persistent background task queue with timeline visibility
- `project_map` — high-level project structure visualization
### Code Analysis & Review
- `review` — structured code review for files, git diffs, or GitHub PRs
- `run_tests` — run `cargo test` with optional arguments
- `diagnostics` — report workspace, git, sandbox, and toolchain info
### Sub-Agent Orchestration
- `agent_spawn` / `delegate_to_agent` — launch background agents for focused tasks
- `agent_swarm` — orchestrate multiple sub-agents with dependencies
- `agent_result` / `agent_list` / `agent_cancel` / `agent_wait` / `wait` / `send_input` — manage running agents
- `multi_tool_use.parallel` — execute multiple read-only tools in parallel
### Structured Data
- `weather` — daily weather forecast for a location
- `finance` — latest price for stocks, funds, indices, or cryptocurrency
- `sports` — schedules or standings for a league
- `time` — current time for a UTC offset
- `calculator` — evaluate basic arithmetic expressions
### Interaction
- `request_user_input` — ask the user structured or multiple-choice questions
### MCP Integration (when configured)
- `mcp_read_resource`, `mcp_get_prompt` — read context from external MCP servers
- `list_mcp_resources`, `list_mcp_resource_templates` — explore available MCP resources
All file tools respect the `--workspace` boundary unless `/trust` is enabled (YOLO enables trust automatically). MCP tools use the same approval pipeline as built-in tools; only trusted MCP servers should be configured.
**Note on token tracking**: DeepSeek models have a 128k context window. If token counts appear inflated (e.g., >128k), this is likely a tracking bug; use `/compact` to summarize earlier context and free up space.
## Configuration
The TUI stores its config at `~/.deepseek/config.toml`:
```toml
api_key = "sk-..."
default_text_model = "deepseek-v3.2" # optional
allow_shell = false # optional
max_subagents = 3 # optional (1-20)
```
Any valid DeepSeek model ID is accepted for `default_text_model` (for example, future IDs such as `deepseek-v4-mini` once available).
### Environment Variables
| Variable | Purpose |
|----------|---------|
| `DEEPSEEK_API_KEY` | API key (overrides config file) |
| `DEEPSEEK_BASE_URL` | API endpoint (default: `https://api.deepseek.com`) |
| `DEEPSEEK_PROFILE` | Select a `[profiles.<name>]` section from config |
| `DEEPSEEK_CONFIG_PATH` | Override config file location |
Additional overrides: `DEEPSEEK_MCP_CONFIG`, `DEEPSEEK_SKILLS_DIR`, `DEEPSEEK_NOTES_PATH`, `DEEPSEEK_MEMORY_PATH`, `DEEPSEEK_ALLOW_SHELL`, `DEEPSEEK_APPROVAL_POLICY`, `DEEPSEEK_SANDBOX_MODE`, `DEEPSEEK_MAX_SUBAGENTS`, `DEEPSEEK_ALLOW_INSECURE_HTTP`.
Optional local audit log (off by default): set `DEEPSEEK_TOOL_AUDIT_LOG=/path/to/audit.jsonl` to record tool approval decisions and tool outcomes as JSONL events.
See `config.example.toml` and `docs/CONFIGURATION.md` for the full reference.
All file tools respect the `--workspace` boundary unless `/trust` is enabled.
## Examples
```bash
# Interactive chat (default)
# Interactive chat
deepseek
# One-shot prompt (non-interactive, prints and exits)
# One-shot prompt
deepseek -p "Explain the borrow checker in two sentences"
# List models from the configured API endpoint
deepseek models
# Agentic execution with auto-approve
deepseek exec --auto "Fix all clippy warnings in this project"
# Resume latest session
deepseek --continue
# Work on a specific project directory
# Work on a specific project
deepseek --workspace /path/to/project
# Review staged git changes
deepseek review --staged
# List saved sessions
deepseek sessions --limit 50
# Start the runtime API server
deepseek serve --http
# Shell completions
deepseek completions zsh > _deepseek
deepseek completions bash > deepseek.bash
deepseek completions fish > deepseek.fish
# Runtime API server (localhost by default)
deepseek serve --http --host 127.0.0.1 --port 7878
# MCP stdio server mode
deepseek serve --mcp
# Verify your environment
deepseek doctor
```
## Runtime API (HTTP/SSE)
## Configuration
`deepseek serve --http` starts a local runtime API for external clients.
Config lives at `~/.deepseek/config.toml`:
Default bind: `127.0.0.1:7878`
```toml
api_key = "sk-..."
default_text_model = "deepseek-v3.2" # optional
allow_shell = false # optional
max_subagents = 3 # optional (1-20)
```
Core endpoints:
- `GET /health`
- `GET /v1/sessions`
- `POST /v1/stream` (backward-compatible single-turn SSE wrapper)
- `POST /v1/threads`
- `GET /v1/threads`
- `GET /v1/threads/{id}`
- `POST /v1/threads/{id}/resume`
- `POST /v1/threads/{id}/fork`
- `POST /v1/threads/{id}/turns`
- `POST /v1/threads/{id}/turns/{turn_id}/steer`
- `POST /v1/threads/{id}/turns/{turn_id}/interrupt`
- `POST /v1/threads/{id}/compact`
- `GET /v1/threads/{id}/events` (SSE replay/live, optional `since_seq`)
- `GET /v1/tasks`
- `POST /v1/tasks`
- `GET /v1/tasks/{id}`
- `POST /v1/tasks/{id}/cancel`
Key environment variables:
Runtime semantics:
- explicit durable Thread/Turn/Item lifecycle with IDs and statuses
- multi-turn continuity on the same thread
- one active turn per thread (overlap rejected with `409`)
- interrupt transitions to terminal `interrupted` only after cleanup
- steer support for active turns
- compaction surfaced as first-class lifecycle items (`auto` + `manual`)
- replayable per-thread event timeline for API/TUI clients
| Variable | Purpose |
|----------|---------|
| `DEEPSEEK_API_KEY` | API key (overrides config file) |
| `DEEPSEEK_BASE_URL` | API endpoint (default: `https://api.deepseek.com`) |
Task queue semantics:
- durable task storage under `~/.deepseek/tasks` (override with `DEEPSEEK_TASKS_DIR`)
- restart-safe recovery (in-progress tasks are re-queued on startup)
- bounded worker pool via `deepseek serve --http --workers <1-8>`
- task execution linked to runtime thread/turn timelines
See [`config.example.toml`](config.example.toml) and [`docs/CONFIGURATION.md`](docs/CONFIGURATION.md) for the full reference.
Security caveat:
- this server is local-first and assumes trusted local access
- no built-in auth/TLS/multi-user isolation
- do not expose it directly to untrusted networks without your own auth/proxy controls
## Runtime API
`deepseek serve --http` starts a local HTTP/SSE API on `127.0.0.1:7878` for external clients. Supports threads, multi-turn conversations, task queues, and live event streaming.
See [`docs/RUNTIME_API.md`](docs/RUNTIME_API.md) for endpoints and usage.
## Keyboard Shortcuts
| Key | Action |
|-----|--------|
| `Enter` | Send message |
| `Alt+Enter` / `Ctrl+J` | Insert newline |
| `Tab` | Autocomplete or cycle modes |
| `Esc` | Cancel request / clear input |
| `Ctrl+C` | Cancel or exit |
| `Ctrl+K` | Command palette |
| `Ctrl+R` | Search past sessions |
| `F1` | Help overlay |
| `PageUp` / `PageDown` | Scroll transcript |
## Troubleshooting
| Problem | Fix |
|---------|-----|
| No API key | Set `DEEPSEEK_API_KEY` or run `deepseek` to complete onboarding |
| Config not found | Check `~/.deepseek/config.toml` (or `DEEPSEEK_CONFIG_PATH`) |
| Config not found | Check `~/.deepseek/config.toml` (or set `DEEPSEEK_CONFIG_PATH`) |
| Wrong region | Set `DEEPSEEK_BASE_URL` to `https://api.deepseeki.com` (China) |
| Session issues | Run `deepseek sessions` then `deepseek --resume latest` |
| Skills missing | Run `deepseek setup --skills` (add `--local` for workspace-local) |
| MCP tools missing | Run `deepseek mcp init`, then restart |
| Sandbox errors (macOS) | Run `deepseek doctor` to confirm sandbox availability |
| Finance tool returns no data | Currently, the finance tool relies on Stooq which may be unavailable; use `web.run` for financial data |
| Token/cost tracking inaccurate | This is a known bug; metrics are approximate. Use `/compact` to manage context |
| Sandbox errors (macOS) | Run `deepseek doctor` |
## Documentation
@@ -292,7 +164,7 @@ cargo clippy
cargo fmt
```
See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.
See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
## License
roadmap.md
-13
View File
@@ -1,13 +0,0 @@
# Roadmap
This roadmap captures planned work after the 0.3.8 line. Dates are intentionally omitted; versions are the delivery targets.
## 0.3.9 (Planned)
- Duo mode groundwork: refine prompts, validation flow, and UX surfacing for player/coach phases.
- Documentation: publish a concise Duo spec and user workflow guide.
- Tooling: tighten phase transitions and reporting in `duo_*` tools.
## 0.4.0 (Planned)
- RLM mode reintroduction: align design with the MIT RLM paper (REPL-style interaction + recursive sub-calls).
- External memory UX: improved loading/query ergonomics and clear persistence semantics.
- Documentation: RLM architecture and usage guide, with explicit parity notes.