deepy-cli 0.1.14

Deepy - Vibe coding for DeepSeek models in your terminal

Deepy

A terminal coding agent built for DeepSeek.
Read projects, edit files, run commands, search the web, and keep long project context in one recoverable terminal session.

Website · 中文文档 · Quick Start · Daily Workflow

What Deepy Does

Deepy is a Python CLI coding agent for DeepSeek's OpenAI-compatible models. It keeps the working loop inside your terminal: inspect a project, ask questions, modify code, run validation commands, search or fetch web pages, and resume the same project session later.

Deepy is optimized for DeepSeek V4 thinking mode, long context, cache-friendly prompting, and a Rich terminal UI that makes the agent's actions visible instead of hiding tool calls behind chat text.

Why Use It

• DeepSeek-first defaults: starts with deepseek-v4-pro, thinking enabled, and reasoning_effort=max. Use /model to switch V4 Pro / V4 Flash and choose none, high, or max thinking strength.
• Project-aware coding tools: read files, write new files, modify existing files with stale-write protection, run shell commands, and review readable diffs.
• Visible terminal transcript: thinking, tool calls, shell output, usage, context status, and command results are shown in the terminal.
• Research from the terminal: use WebSearch for discovery and WebFetch when you already have an exact URL.
• Long-session continuity: JSONL sessions, /resume, /new, context window status, automatic compacting, and manual /compact.
• Local command mode: type !cmd to run a non-interactive local shell command without sending it to the model; the result is still saved as context.
• Cross-platform shell handling: POSIX shell, PowerShell, cmd, Windows paths, UTF-8 output, CRLF editing, and non-interactive Windows local command mode.

See It Work

Terminal-Centered Agent Loop

Deepy keeps model reasoning, WebFetch, shell output, and status lines visible in one transcript.

Code Editing With Reviewable Diff

File edits are shown with path information and readable diff output so you can inspect what changed before continuing.

Search, Fetch, And Local Commands

Use WebSearch / WebFetch for external context, @ for file mentions, and ! for direct local commands.

Quick Start

1. Install uv:

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows PowerShell
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

2. Configure a uv mirror.

Linux / macOS: ~/.config/uv/uv.toml

[[index]]
url = "https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple/"
default = true

Windows: %AppData%\uv\uv.toml

[[index]]
url = "https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple/"
default = true

3. Install Deepy:

uv tool install deepy-cli

The installed command is deepy.

4. Configure your DeepSeek API key and start Deepy:

deepy config setup

cd your-project
deepy

Installation Notes

Use this order for a fresh machine:

1. Install uv

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows PowerShell
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

2. Configure a uv mirror

Linux / macOS: ~/.config/uv/uv.toml

[[index]]
url = "https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple/"
default = true

Windows: %AppData%\uv\uv.toml

[[index]]
url = "https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple/"
default = true

3. Install Deepy

uv tool install deepy-cli

4. Configure and start

deepy config setup

cd your-project
deepy

Upgrade or uninstall Deepy:

uv tool upgrade deepy-cli
uv tool uninstall deepy-cli

Daily Workflow

Inside an interactive Deepy session:

/model       Select model and thinking strength
/resume      Resume a previous project session
/new         Start a fresh session
/compact     Compact the active session context
/theme       Show or change terminal UI theme
@src/app.py  Mention a file in the current project
!pytest -q   Run a local non-interactive command
Esc          Interrupt the current model turn
Ctrl+D       Press twice to quit

Typical usage:

Ask Deepy to inspect a bug, edit files, run tests, and summarize what changed.
Use @ to reference files precisely.
Use ! for commands you want to run directly without model mediation.
Use /resume when returning to a project later.
Use /compact when a long session needs a durable summary.

Configuration

Deepy uses TOML configuration at ~/.deepy/config.toml.

[model]
api_key = "sk-..."
name = "deepseek-v4-pro"
base_url = "https://api.deepseek.com"
thinking = true
reasoning_effort = "max"

[context]
window_tokens = 1048576
compact_trigger_ratio = 0.8
reserved_context_tokens = 50000
compact_preserve_recent_messages = 2

[ui]
theme = "auto" # auto, dark, or light

Set config without the interactive wizard:

deepy config init --api-key sk-... --model deepseek-v4-pro
deepy config theme light

WebSearch uses Deepy's hosted SearXNG endpoint by default. You can override it:

[tools.web_search]
searxng_url = "https://your-searxng.example/"

Command Reference

deepy --version
deepy config setup
deepy config reset
deepy config theme
deepy doctor
deepy doctor --live --json
deepy status
deepy skills list
deepy sessions list
deepy sessions show <session-id>
deepy run "summarize this project"

Project Rules And Skills

Deepy automatically loads project instructions from:

• AGENTS.md
• .deepy/skills/*/SKILL.md

This lets each repository define local conventions, commands, review rules, and domain-specific workflows without changing global config.

Development

uv sync --group dev
uv run pytest
uv run ruff check
uv run pyright
uv build

The Python package is built from src/deepy. GitHub Pages files and screenshot assets live outside the package directory and are not included in the wheel.