Update README.md
Browse files# YCode
```
██╗ ██╗ ██████╗ ██████╗ ██████╗ ███████╗
╚██╗ ██╔╝██╔════╝██╔═══██╗██╔══██╗██╔════╝
╚████╔╝ ██║ ██║ ██║██║ ██║█████╗
╚██╔╝ ██║ ██║ ██║██║ ██║██╔══╝
██║ ╚██████╗╚██████╔╝██████╔╝███████╗
╚═╝ ╚═════╝ ╚═════╝ ╚═════╝ ╚══════╝
```
YCode is an AI coding agent that runs in your terminal. Start it inside a project, describe a task in plain English, and it works through it: it looks around the repository, makes a short plan, edits files, runs your tests and build, reads any failures, fixes them, and then tells you what changed.
**YCode works out of the box with no API key and no training.** By default it answers with **YCode-LM**, its own coding language model, trained from scratch and shipped in this repository (`models/`). Clone, install, and run `ycode`: nothing to sign up for, no key to paste, nothing sent over the network. See [Answering without an API key](#answering-without-an-api-key).
YCode-LM is the only model YCode needs. If you also want full autonomous coding (reading, editing and running files in your project, as in the example below), you can optionally plug in Claude: see [Using Claude (optional)](#using-claude-optional). Everything else always runs locally: the tool system, the permission checks and the terminal UI. The model sits behind a small provider interface, so you can add other LLM providers without rewriting the agent.
With Claude (`--provider anthropic`), YCode works through whole tasks:
```text
ycode> Fix the failing add() test
◇ Plan
▸ 1. Read calc.py
○ 2. Fix add
○ 3. Run tests
◇ Reading calc.py
✓ Read calc.py (2 of 2 lines)
◇ Editing calc.py
✓ Edited calc.py (+1 -1)
@@ -1,2 +1,2 @@
def add(a, b):
- return a - b
+ return a + b
◇ Running `python -m pytest -q`
✓ Succeeded (exit code 0, 0.3s)
Fixed `add` in calc.py; pytest passes (1 test).
Changes:
M calc.py
Commands:
✓ python -m pytest -q
✓ YCode completed the task. (5 steps)
```
## Features
- **Terminal first.** Uses Rich for output: spinners, streamed Markdown, syntax-highlighted diffs. Uses prompt_toolkit for input: persistent history, multiline editing, and tab completion for `/commands`.
- **Autonomous agent loop.** The model can make many tool calls per task, parallel calls included, until it is done. A configurable step limit (default 50) stops runaway loops.
- **Planning.** For non-trivial work the model writes a short plan through an `update_plan` tool and keeps it current. For trivial requests it skips the plan.
- **Verification.** The model picks verification commands from your project type (`npm test`, `pytest`, `cargo test`, ...), reads failures and iterates. It is told never to claim success it did not verify.
- **Tools:** `read_file`, `write_file`, `edit_file`, `list_directory`, `search_files`, `find_files`, `run_command`, `git_status`, `git_diff`, `git_log`, `git_branch`, `update_plan`.
- **Security.** Commands are classified as SAFE, REQUIRES_APPROVAL or BLOCKED. Risky ones need an explicit `y`. File access is confined to the workspace, and API keys are stripped from the environment that commands run in.
- **Repository awareness.** Detects Node.js, TypeScript, JavaScript, React, Next.js, Vue, Python, Java, Kotlin, C/C++, Rust, Go, Flutter/Dart, Ruby and PHP projects, plus the package manager and the likely test and build commands. Large generated directories are ignored.
- **Diff awareness.** After each task YCode summarizes the changed files and the commands it ran. `/diff` shows the full diff.
- **Project instructions.** A `YCODE.md` file in the repository is loaded into the agent's instructions.
- **Layered configuration:** global and per-project TOML files, environment variables and CLI flags.
- **No API key needed.** The default provider is YCode's own bundled model. It answers Python documentation questions exactly from Python's built-in docs, and writes functions that are checked to compile and define what you asked for. Everything runs offline.
- **Model-agnostic core.** The agent depends only on `LLMProvider`. There are two implementations: your own local model (default) and Claude (optional).
- **Your own LLM.** `ycode-lm` builds a byte-level BPE tokenizer and a GPT-style transformer from scratch, pretrains it on code, and instruction-tunes it to answer programming questions. Four trained versions ship with the repository, up to the 1.5B-parameter v5.
## Architecture
```text
┌──────────────┐
│ YCode CLI │ cli.py, commands.py, ui/
└──────┬───────┘
│
┌──────▼───────┐
│ Agent Engine │ agent/loop.py, planner.py, context.py, prompts.py
└──────┬───────┘
│
┌────────▼────────┐
│ LLM Provider │ llm/base.py (interface), llm/anthropic.py
└────────┬────────┘
│
Claude API
│
┌────────▼────────┐
│ Tool Execution │ tools/ (+ security/permissions.py)
└────────┬────────┘
┌────────────┼────────────┐
▼ ▼ ▼
Filesystem Terminal Git
```
```text
ycode/
├── __main__.py # python -m ycode
├── cli.py # argument parsing, REPL, graceful shutdown
├── app.py # wires config, context, permissions, tools, provider, agent, UI
├── commands.py # /help /clear /status /diff /files /model /plan /approval /exit
├── config.py # layered TOML + env + CLI configuration
├── errors.py # user-facing error hierarchy (no raw tracebacks)
├── agent/
│ ├── loop.py # the agent loop, step limit, interruption handling
│ ├── planner.py # Plan model + update_plan tool
│ ├── context.py # project detection, YCODE.md loading
│ └── prompts.py # system prompt
├── llm/
│ ├── base.py # provider-neutral messages, ToolSpec, LLMProvider
│ ├── anthropic.py # Claude via the official anthropic SDK (streaming)
│ └── local.py # your own YCode-LM model (answer-only, no API key)
├── lm/ # YCode-LM: the from-scratch model; assist.py answers docs questions and checks code
│ ├── tokenizer.py # byte-level BPE tokenizer for code
│ ├── model.py # GPT transformer: RoPE, RMSNorm, SwiGLU, KV-cache sampling
│ ├── data.py # corpus collection, instruction-pair extraction, encoding
│ ├── train.py # pretraining + instruction tuning, checkpoints, resume
│ ├── optim.py # Muon optimizer (v3) + AdamW wiring
│ ├── evaluate.py # bits/byte on held-out code, pass@k on executed problems
│ ├── generate.py # inference (chat + completion, streaming)
│ └── cli.py # the `ycode-lm` command
├── tools/
│ ├── base.py # Tool, ToolRegistry (validation + dispatch), ToolResult
│ ├── filesystem.py # read/write/edit/list
│ ├── search.py # regex content search, glob file search
│ ├── terminal.py # run_command (timeouts, output capture, Ctrl+C)
│ └── git.py # git helpers + read-only git tools
├── security/
│ └── permissions.py # command classifier, PathGuard, PermissionManager
└── ui/
├── banner.py # ASCII banner
├── console.py # Rich renderer (implements AgentEvents)
└── prompts.py # prompt_toolkit input with history/multiline
```
The dependencies point one way. The agent knows nothing about Rich or Anthropic: it talks to an `LLMProvider` and reports progress through `AgentEvents` callbacks. The UI implements those callbacks. Tools don't know about the model.
**Adding a provider:** subclass `LLMProvider` in `ycode/llm/`, translate the neutral `UserMessage`/`AssistantMessage`/`ToolResultsMessage` types to your API's format, and register it in `ycode/llm/__init__.py:create_provider`. Assistant messages carry an opaque `provider_data` field. Your provider can use it to replay its own native content exactly, which Claude needs for its thinking blocks.
## Requirements
- Python 3.10+
- About 4 GB of free RAM for the default model, YCode-LM v5 (1.5B parameters). With less, YCode uses the smaller v4 (about 1 GB) automatically.
- Git, to clone the repository (it contains the trained models) and for the git features
That's all. **No API key, no account and no internet connection are needed** to run YCode.
## Installation
```bash
git clone https://github.com/yazhiniyanMS/Code-agent.git
cd Code-agent
python -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -e . # includes PyTorch for the built-in model
ycode # start asking questions: no API key, no training
```
This installs a `ycode` command. `python -m ycode` works too. Install from the clone (as above) rather than from a bare package: the trained models live in the repository's `models/` folder. To keep them elsewhere, set `YCODE_MODELS_DIR`.
Optional extras:
```bash
pip install -e ".[hf]" # Hugging Face: