Metadata-Version: 2.4
Name: xcoding
Version: 0.1.2
Summary: xcoding by @c7s89r — a local-model coding agent. Claude Code, but powered by Ollama or llama.cpp.
Author-email: c7s89r <c7s89r@users.noreply.github.com>
Maintainer-email: c7s89r <c7s89r@users.noreply.github.com>
License: MIT
Project-URL: Homepage, https://github.com/c7s89r/xcode
Project-URL: Repository, https://github.com/c7s89r/xcode
Project-URL: Issues, https://github.com/c7s89r/xcode/issues
Keywords: cli,coding-agent,ollama,llama.cpp,ai,local-llm
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: openai>=1.30.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: rich>=13.7.0
Requires-Dist: prompt_toolkit>=3.0.0
Requires-Dist: discord.py>=2.3.0
Dynamic: license-file

# xcoding · by [@c7s89r](https://github.com/c7s89r)

A local-model coding agent by **@c7s89r** — like Claude Code, but it talks to a
model running on your own machine instead of a cloud API.

> **✅ Works with [Ollama](https://ollama.com) for now.** Just install Ollama,
> pull a tool-capable model, then `pip install xcoding` and run `xcode`.
> (llama.cpp support is in too, but Ollama is the tested path.)

It auto-detects whichever backend is running, gives the model tools to read/write
files and run shell commands, and loops until your task is done. Every file write
and every shell command asks for your approval first.

### Quick start (Ollama)

```bash
ollama serve
ollama pull qwen2.5-coder     # a model that's good at tool use
pip install xcoding
xcode
```

## Install

```bash
pip install xcoding
```

Then just run `xcode` from any project folder.

Or from source:

```bash
pip install -e .
```

(Python 3.9+. Pulls in `openai`, `httpx`, `rich`.)

## Run a backend

**Ollama** (easiest — supports tool-calling natively):

```bash
ollama serve
ollama pull qwen2.5-coder        # a model that's good at tool use
```

**llama.cpp** (raw GGUF files):

```bash
llama-server -m your-model.gguf   # listens on :8080, OpenAI-compatible
```

> Tool-calling quality depends heavily on the model. Use a model trained for it
> (e.g. `qwen2.5-coder`, `llama3.1`, `mistral-nemo`). Tiny models will struggle.

## Use it

```bash
xcode
# or:  python -m xcode
```

Then just talk to it:

```
› add a /health endpoint to app.py that returns {"ok": true}
```

In-REPL commands: `/help`, `/models`, `/model`, `/init`, `/todos`, `/perms`,
`/compact`, `/sessions`, `/resume`, `/reset`, `/exit`.

- Replies **stream** live; the prompt shows a **context meter** (`~3.2k/8k`).
- Writes/commands ask `y / n / a`; **a** ("always") is saved to
  `.xcode/permissions.json`. Edits show a **colored diff** preview.
- Attach files inline with `@path` (e.g. `explain @xcode/agent.py`).
- The agent tracks a **todo list** for multi-step work (`/todos` to view).
- Old turns are **auto-compacted** when the context meter fills; `/compact`
  forces it. Conversations are **saved** per project — `xcode --resume` or
  `/resume` to pick up where you left off.
- Drop an **XCODE.md** at the repo root (or run `/init`) and it's auto-loaded
  as project memory.

### Modes (shift+tab to cycle)

- **·· normal** — asks before writes/commands
- **⏵⏵ auto** — runs & writes without asking
- **◷ plan** — read-only; explores but makes no changes

### Sub-agents, web, MCP, hooks

- `spawn_agent` lets the model delegate an isolated subtask to a fresh context.
- `web_search` (DuckDuckGo) and `web_fetch` give it internet access.
- Drop a `.xcode/settings.json` to add **hooks** (run a formatter after every
  edit), **env** vars, seed **permissions**, and declare **MCP servers**:

```json
{
  "hooks": { "after_edit": ["ruff format {path}"] },
  "permissions": { "commands": ["git", "ls", "python"] },
  "mcpServers": {
    "fs": { "command": "npx",
            "args": ["-y", "@modelcontextprotocol/server-filesystem", "."] }
  }
}
```

MCP tools show up to the model as `mcp__<server>__<tool>`.

### Headless / scripting

```bash
xcode -p "summarize what this repo does"          # read-only, prints, exits
xcode -p "bump the version to 0.2.0" --yes        # auto-approve writes
xcode -p "what changed?" --resume                 # continue last session
```

## Configuration (env vars)

| var              | meaning                                              |
|------------------|------------------------------------------------------|
| `XCODE_BASE_URL` | point straight at any OpenAI-compatible `/v1` URL    |
| `XCODE_MODEL`    | force a specific model name                          |
| `XCODE_API_KEY`  | token if your endpoint needs one (default `local`)   |
| `XCODE_MAX_STEPS`| max tool round-trips per turn (default 25)           |

## How it works

```
cli.py       REPL + permission prompts (the only UI code)
agent.py     the loop: model ⇄ tools until it stops calling tools
backends.py  auto-detect Ollama (:11434) / llama.cpp (:8080)
tools.py     read_file, write_file, list_dir, run_command + JSON schemas
config.py    system prompt + knobs
```

## Roadmap

- [x] Streaming token output
- [x] `edit_file` (targeted edits instead of full rewrites)
- [x] `grep` / `glob_files` search tools
- [x] Persistent permission rules ("always allow `git …`")
- [x] `/model` picker + smart default-model selection
- [x] Context compaction for long sessions + context meter
- [x] Diff-style preview when confirming edits
- [x] Project memory (XCODE.md) + `/init`
- [x] Todo/task tracking
- [x] Session save + `--resume`
- [x] Headless mode (`-p`) + `@file` mentions
- [x] Web fetch / web search tools
- [x] Sub-agents (delegate a subtask to a fresh context)
- [x] MCP server support
- [x] Hooks + settings.json
- [x] Themes + ghost logo, shift+tab mode cycling (normal/auto/plan)

## Made by

Built by **@c7s89r** (nzv).

- GitHub: [@c7s89r](https://github.com/c7s89r)
- Discord: `c7s89r`

MIT licensed — see [LICENSE](LICENSE).
