dgf1988/codewhale

Files

T

Hunter Bown 432082e956 docs(agents): document deepseek as the canonical CLI binary

The user-facing entry point for every flow is the `deepseek` dispatcher
(crates/cli), not `deepseek-tui`. Future agent sessions and example
commands should default to `deepseek` / `cargo run --bin deepseek`.
Mirror the same directive in the local CLAUDE.md (gitignored).

2026-04-26 14:01:30 -05:00

3.1 KiB

Raw Blame History

Project Instructions

This file provides context for AI assistants working on this project.

Project Type: Rust

Commands

Build: cargo build (default-members include the deepseek dispatcher)
Test: cargo test --workspace --all-features
Lint: cargo clippy --workspace --all-targets --all-features
Format: cargo fmt --all
Run (canonical): deepseek — use the deepseek binary, not deepseek-tui. The dispatcher delegates to the TUI for interactive use and is the supported entry point for every flow (deepseek, deepseek -p "...", deepseek doctor, deepseek mcp …, etc.).
Run from source: cargo run --bin deepseek (or cargo run -p deepseek-tui-cli).
Local dev shorthand: after cargo build --release, run ./target/release/deepseek.

Build Dependencies

Rust 1.85+ (for the workspace)

Documentation

See README.md for project overview, docs/ARCHITECTURE.md for internals.

DeepSeek-Specific Notes

Thinking Tokens: DeepSeek models output thinking blocks (ContentBlock::Thinking) before final answers. The TUI streams and displays these with visual distinction.
Reasoning Models: deepseek-v4-pro and deepseek-v4-flash are the documented V4 model IDs. Legacy deepseek-chat and deepseek-reasoner are compatibility aliases for deepseek-v4-flash.
Large Context Window: DeepSeek V4 models have 1M-token context windows. Use search tools to navigate efficiently.
API: OpenAI-compatible Chat Completions (/chat/completions) is the documented DeepSeek API path. Base URL configurable for global (api.deepseek.com) or China (api.deepseeki.com); /v1 is accepted for OpenAI SDK compatibility, and /beta is only needed for beta features such as strict tool mode, chat prefix completion, and FIM completion.
Thinking + Tool Calls: In V4 thinking mode, assistant messages that contain tool calls must replay their reasoning_content in all subsequent requests or the API returns HTTP 400.

GitHub Operations

Use the gh CLI (/opt/homebrew/bin/gh) for all GitHub operations — issues, PRs, branches, labels. It's already authenticated as Hmbown (token scopes: gist, read:org, repo, workflow). Examples:

List open issues: gh issue list --state open --limit 20
View an issue: gh issue view <number>
Create an issue branch: gh issue develop <number> --branch-name feat/issue-<number>-<slug>
Create a PR: gh pr create --base feat/v0.6.2 --title "..." --body "..."
Check PR status: gh pr view <number>

Prefer gh over fetch_url or web_search for GitHub data — it's faster, authenticated, and avoids rate limits.

Important Notes

Token/cost tracking inaccuracies: Token counting and cost estimation may be inflated due to thinking token accounting bugs. Use /compact to manage context, and treat cost estimates as approximate.
Modes: Three modes — Plan (read-only investigation), Agent (tool use with approval), YOLO (auto-approved). See docs/MODES.md for details. All three modes can call the rlm_query tool for parallel/batched LLM fan-out (crates/tui/src/tools/rlm_query.rs).

3.1 KiB Raw Blame History