cbyzt-ycode 0.3.1

YCode — a minimal, professional code agent powered by DeepSeek

YCode

A minimal, professional command-line code agent powered by DeepSeek. No IDE — launch it from PowerShell, give it a task, and it edits files, runs commands, and completes work through a tool loop.

• Agentic tool loop — reads, writes, edits, greps, and runs shell/background commands; read-only actions run freely, writes and shell ask first (y/n/a).
• Cross-session memory — remembers your preferences and project constraints in .ycode/memory/ (project) and ~/.ycode/memory/ (global) and reloads them each session.
• Context management — automatically compacts long conversations and shows per-turn token usage so it never overflows the model's context.
• Subagents — delegates self-contained subtasks to autonomous workers that report back (sequentially, or several read-only ones in parallel), keeping the main context clean.
• MCP client — connects to any Model Context Protocol server and exposes its tools to the model.
• Extensible — markdown skills, plus a web_fetch tool for docs.
• Scriptable — one-shot mode (ycode "task" -y) for unattended runs.

Install

Requires Python 3.11+ and a DeepSeek API key.

For users — pick one:

# Recommended: isolated global install via pipx
pipx install cbyzt-ycode

# Or plain pip
pip install cbyzt-ycode

# Or straight from GitHub (no PyPI needed)
pipx install git+https://github.com/cbyzt/ycode

# Or from a wheel file someone sent you
pip install cbyzt_ycode-0.3.1-py3-none-any.whl

For development — from a clone of the repo:

pip install -e .            # editable install
pip install -e ".[dev]"     # + pytest, then run: pytest

The test suite stubs the model client, so it needs no API key or network.

Set your API key

YCode needs a DeepSeek API key (get one at https://platform.deepseek.com). It is read from the DEEPSEEK_API_KEY environment variable:

$env:DEEPSEEK_API_KEY = "sk-..."     # this shell only
setx DEEPSEEK_API_KEY "sk-..."       # persist across shells (reopen the terminal)

Run

ycode                      # interactive REPL (or: python -m ycode)
ycode "add a /health route"   # one-shot: run one task, then exit
ycode "fix the failing test" -y   # -y auto-approves file/shell actions
ycode --model pro "..."    # pick the model for this run

Type a request in plain language. YCode will read files, propose edits, and run commands to accomplish it. Read-only actions run automatically; anything that writes files or runs a shell command asks for confirmation first (y/n/a).

Commands

Command	Description
/help	List commands and skills
/clear	Clear the conversation (keeps the system prompt)
/compact	Summarize older turns to free up context
/memory	Show what YCode remembers across sessions
/forget <name>	Delete a stored memory by name
/mcp	Show connected MCP servers and their tools
/model [flash|pro]	Show or switch model
/reload	Hot-reload tools, skills & prompt (development)
/init	Scan the project and generate YCODE.md
/exit	Quit

Models

• flash → deepseek-v4-flash (default: fast, cheap, 1M context)
• pro → deepseek-v4-pro (frontier reasoning for hard tasks)

Skills

A skill is a directory with a SKILL.md file:

---
name: my-skill
description: One line the model uses to decide relevance.
invocation: both      # slash | auto | both
kind: prompt          # prompt (inject body) | control (run Python)
---
Markdown instructions injected into the conversation when the skill runs.

Built-in skills live in ycode/skills/builtin/. Project skills are discovered from .ycode/skills/ in your working directory. invocation controls triggering: typed /name, model-initiated via load_skill, or both.

Tools

read_file, write_file, edit_file, ls, glob, grep, run_shell, web_fetch (fetch a URL as text), ask_user (interactive arrow-key selector), load_skill, save_memory, forget_memory, spawn_agent, spawn_agents.

Background processes — for dev servers, watchers, and anything that does not exit on its own:

• run_background — start a command in the background and return immediately
• list_processes — list background processes and their status
• read_output — read a background process's captured output
• stop_process — stop a background process and its child processes

Background processes are all terminated automatically when YCode exits.

Memory

YCode keeps durable facts across sessions and loads them into every new conversation, so you don't repeat yourself. It saves them as one Markdown file per fact, in two scopes:

• project — .ycode/memory/ in your working directory (constraints and preferences specific to this repo)
• global — ~/.ycode/memory/ (facts about you that hold across all projects)

The model decides what's worth remembering (a stated preference, feedback on how you want it to work, a non-obvious constraint) and calls save_memory; it won't store things already in the code, git, or YCODE.md. Use /memory to see what's stored and /forget <name> (or the forget_memory tool) to drop a fact.

Subagents

For larger tasks, YCode can delegate to subagents — fresh agents with their own context and the same tools, that run autonomously and report back a concise summary, keeping the main conversation uncluttered.

• spawn_agent — one subagent (full tools) for a self-contained subtask.
• spawn_agents — several read-only research subagents in parallel, for independent investigation (inspect many files at once, research several questions). Each can only read (read_file/ls/glob/grep/web_fetch), so parallel runs never conflict; their reports come back together.

Subagents can't spawn further subagents or prompt you, so they always terminate.

MCP servers

YCode is an MCP client: drop a .ycode/mcp.json in your project and its servers' tools become available to the model (as mcp__<server>__<tool>, gated by the same confirmation prompt).

{
  "mcpServers": {
    "fs": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "."] }
  }
}

Run /mcp to see connection status. Servers are started on launch and stopped on exit.

Context management

Long sessions never overflow the context window: YCode shows per-turn token usage and, once the conversation grows past a threshold, automatically compacts it — summarizing the older turns into one note while keeping the system prompt and the most recent turns. Run /compact to trigger it manually.

Building & publishing (maintainers)

# Build sdist + wheel into dist/
pip install build
python -m build

# Publish to PyPI (bump `version` in pyproject.toml first)
pip install twine
twine upload dist/*          # username __token__, password = your PyPI API token

Test the upload against TestPyPI first with twine upload -r testpypi dist/*.

Standalone executable (no Python required)

pip install pyinstaller
pyinstaller --onefile --name ycode ^
    --add-data "ycode/skills/builtin;ycode/skills/builtin" ^
    ycode/__main__.py

The --add-data flag is required — PyInstaller does not bundle the SKILL.md files automatically. The result is dist/ycode.exe.