Metadata-Version: 2.4
Name: cbyzt-ycode
Version: 0.2.0
Summary: YCode — a minimal, professional code agent powered by DeepSeek
Author: cbyzt
License-Expression: MIT
Project-URL: Homepage, https://github.com/cbyzt/ycode
Project-URL: Repository, https://github.com/cbyzt/ycode
Keywords: ai,agent,cli,deepseek,coding-assistant
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: openai>=1.40
Requires-Dist: rich>=13.7
Requires-Dist: pyyaml>=6.0
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Dynamic: license-file

# 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, keeping the main context clean.
- **MCP client** — connects to any [Model Context Protocol](https://modelcontextprotocol.io)
  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:

```powershell
# 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.2.0-py3-none-any.whl
```

**For development** — from a clone of the repo:

```powershell
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:

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

## Run

```powershell
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:

```yaml
---
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`.

**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 a self-contained subtask to a **subagent** —
a fresh agent with its own context and the same tools. It runs autonomously and
returns only a concise summary, so the main conversation stays uncluttered.
Subagents can't spawn further subagents or prompt you, so they always terminate.

## MCP servers

YCode is an [MCP](https://modelcontextprotocol.io) 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).

```json
{
  "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)

```powershell
# 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)

```powershell
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`.
