diff --git a/README.md b/README.md index 47afeaba..2fa4f35a 100644 --- a/README.md +++ b/README.md @@ -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.]` 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 diff --git a/roadmap.md b/roadmap.md deleted file mode 100644 index 238a5bd8..00000000 --- a/roadmap.md +++ /dev/null @@ -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.