Metadata-Version: 2.4
Name: vulpcode
Version: 0.2.0
Summary: Terminal coding agent, multi-provider (Anthropic, OpenAI, Gemini, Ollama, ...)
Project-URL: Homepage, https://github.com/Vulp-Code/vulpcode
Project-URL: Repository, https://github.com/Vulp-Code/vulpcode
Project-URL: Issues, https://github.com/Vulp-Code/vulpcode/issues
Author: Vulpcode Authors
License: MIT
License-File: LICENSE
Keywords: agent,ai,claude,cli,coding-agent,llm,ollama
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development
Classifier: Topic :: Terminals
Requires-Python: >=3.11
Requires-Dist: anthropic>=0.40
Requires-Dist: google-genai>=0.3
Requires-Dist: httpx>=0.27
Requires-Dist: mcp>=1.0
Requires-Dist: ollama>=0.4
Requires-Dist: openai>=1.50
Requires-Dist: prompt-toolkit>=3.0
Requires-Dist: pydantic>=2.5
Requires-Dist: rich>=13.7
Requires-Dist: tomli-w>=1.0
Requires-Dist: typer>=0.12
Provides-Extra: dev
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: respx>=0.21; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
Requires-Dist: mkdocs>=1.6; extra == 'docs'
Requires-Dist: mkdocstrings[python]>=0.26; extra == 'docs'
Requires-Dist: pymdown-extensions>=10.7; extra == 'docs'
Provides-Extra: docs-tools
Requires-Dist: markdown-it-py>=3.0; extra == 'docs-tools'
Requires-Dist: nbformat>=5.10; extra == 'docs-tools'
Requires-Dist: pydot>=2.0; extra == 'docs-tools'
Requires-Dist: pypdf>=4.0; extra == 'docs-tools'
Requires-Dist: python-docx>=1.1; extra == 'docs-tools'
Requires-Dist: pyyaml>=6.0; extra == 'docs-tools'
Requires-Dist: reportlab>=4.0; extra == 'docs-tools'
Requires-Dist: sqlparse>=0.4; extra == 'docs-tools'
Provides-Extra: search
Requires-Dist: duckduckgo-search>=6.0; extra == 'search'
Description-Content-Type: text/markdown

# Vulpcode

**A terminal coding agent that lets you choose the model.**

[![PyPI](https://img.shields.io/pypi/v/vulpcode.svg)](https://pypi.org/project/vulpcode/)
[![Python](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Status](https://img.shields.io/badge/status-alpha-orange.svg)](#status)

Vulpcode is a CLI agent for software engineering tasks — inspired by Claude
Code — that is **provider-agnostic**. The same set of tools, slash commands,
and MCP support, but you decide which model to talk to: paid APIs
(Anthropic, OpenAI, Gemini), local engines (Ollama, LM Studio, vLLM),
OpenAI-compatible gateways (DeepSeek, Groq, OpenRouter), or internal
corporate endpoints.

---

## Highlights

- **Provider-agnostic.** Switch models with a single flag (`--provider`,
  `--model`), without changing your workflow.
- **Privacy-first.** Run fully offline with Ollama, LM Studio, or vLLM. No
  outbound traffic when the chosen provider is local.
- **Pip-native.** Installs like any Python package. No Node, no npm, no
  external runtime.
- **Tool-complete.** Functional parity with the leading agentic CLIs: Bash
  (foreground + background), Read, Write, Edit, MultiEdit, Glob, Grep,
  WebFetch, WebSearch, Task, TodoWrite, NotebookEdit.
- **MCP support.** Connects to any Model Context Protocol server you
  configure; their tools are auto-registered into the agent.
- **Hackable.** ~3k lines of core code, tools as plugins, providers as
  adapters.

---

## Installation

Requires **Python 3.11+**.

```bash
pip install vulpcode
```

Installing inside a virtual environment is recommended:

```bash
python -m venv ~/.venv/vulpcode
source ~/.venv/vulpcode/bin/activate
pip install vulpcode
```

Vulpcode ships two equivalent console scripts: `vulp` (short) and `vulpcode`.

### Optional extras

| Extra           | Adds                                                                      | Use it for                                              |
| --------------- | ------------------------------------------------------------------------- | ------------------------------------------------------- |
| `[dev]`         | `pytest`, `pytest-asyncio`, `ruff`, `mypy`, `respx`                       | Contributors running the test suite                     |
| `[docs]`        | `mkdocs`, `mkdocs-material`, `mkdocstrings[python]`, `pymdown-extensions` | Building the documentation site                         |
| `[search]`      | `duckduckgo-search`                                                       | Using `WebSearch` without a Tavily key                  |
| `[docs-tools]`  | `python-docx`, `reportlab`, `pypdf`, `markdown-it-py`, `nbformat`, `PyYAML`, `sqlparse`, `pydot` | Validators for the `Write*` family (docx/pdf/notebook/etc.) |

```bash
pip install "vulpcode[search]"
pip install "vulpcode[dev,docs]"
pip install "vulpcode[docs-tools]"
```

### From source

```bash
git clone https://github.com/Vulp-Code/vulpcode.git
cd vulpcode
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev,docs,search]"
```

---

## Quick start

```bash
# Verify the install
vulp --version
vulp providers
```

### First chat with Claude

```bash
export ANTHROPIC_API_KEY=sk-ant-...
vulp --auto "say hi in one word"
```

### Run fully offline with Ollama

```bash
ollama pull qwen2.5-coder:7b
vulp --provider ollama --model qwen2.5-coder:7b --auto "explain git rebase"
```

### Use an OpenAI-compatible gateway (e.g. Groq)

```bash
export GROQ_API_KEY=gsk_...
vulp --provider groq --model llama-3.3-70b-versatile
```

### Use an internal corporate endpoint

The library ships two providers for internal corporate `/chatCompletion` endpoints:

| Provider | When to use |
|---|---|
| `internal-llm` | Plain chat only — no file creation, no shell, no agentic loop |
| `internal-llm-agentic` | Full agentic flow via a text-based tool protocol (recommended) |

Both read the same env vars:

```bash
export INTERNAL_LLM_ENDPOINT="https://internal.example.com/v1/chat"
export INTERNAL_LLM_USER_UUID="00000000-0000-0000-0000-000000000000"

# Chat-only mode
vulp --provider internal-llm

# Full agent (creates files, runs validators, retries on syntax errors)
vulp --provider internal-llm-agentic
```

---

## Supported providers

| Provider       | Backend type          | Tools | Vision | Streaming |
| -------------- | --------------------- | :---: | :----: | :-------: |
| `anthropic`    | Anthropic (Claude)    |   x   |   x    |    x      |
| `openai`       | OpenAI (GPT)          |   x   |   x    |    x      |
| `gemini`       | Google (Gemini)       |   x   |   x    |    x      |
| `ollama`       | Local                 |   x   |   x    |    x      |
| `deepseek`     | OpenAI-compatible     |   x   |        |    x      |
| `groq`         | OpenAI-compatible     |   x   |        |    x      |
| `openrouter`   | OpenAI-compatible     |   x   |        |    x      |
| `lmstudio`     | Local                 |   x   |        |    x      |
| `vllm`         | Local                 |   x   |        |    x      |
| `internal-llm` | Corporate endpoint    |       |        |           |
| `internal-llm-agentic` | Corporate endpoint (text-protocol tool calling) | x | | |

Run `vulp providers` to list them at any time.

---

## Built-in tools

| Tool           | Purpose                                                |
| -------------- | ------------------------------------------------------ |
| `Read`         | Read files (text, images, notebooks, PDFs)             |
| `Write`        | Create or overwrite a file                             |
| `Edit`         | Exact string replacement                               |
| `MultiEdit`    | Multiple edits in a single file, atomically            |
| `Bash`         | Run shell commands                                     |
| `BashOutput`   | Stream output from a long-running background process   |
| `KillBash`     | Terminate a background process                         |
| `Glob`         | Find files by pattern                                  |
| `Grep`         | Search file contents                                   |
| `WebFetch`     | Fetch and parse a URL                                  |
| `WebSearch`    | Search the web (Tavily or DuckDuckGo)                  |
| `Task`         | Delegate work to a sub-agent                           |
| `TodoWrite`    | Persistent task list inside a session                  |
| `NotebookEdit` | Edit Jupyter notebook cells                            |

### Validated write tools

Format-specific writers that **parse-and-validate** the content before
saving and write atomically (temp file + rename). If validation fails the
target file is never touched, so the agent can repair the input and retry.

| Tool         | Format    | Validation                                  |
| ------------ | --------- | ------------------------------------------- |
| `WritePy`    | Python    | `compile()` (syntax check)                  |
| `WriteIpynb` | Notebook  | `nbformat` schema                           |
| `WriteMd`    | Markdown  | `markdown-it-py`                            |
| `WriteDocx`  | Word      | `python-docx`                               |
| `WritePdf`   | PDF       | `pypdf` (or `reportlab` for generation)     |
| `WriteJson`  | JSON      | `json.loads`                                |
| `WriteYaml`  | YAML      | `PyYAML` safe-load                          |
| `WriteToml`  | TOML      | `tomllib`                                   |
| `WriteCsv`   | CSV       | `csv` round-trip                            |
| `WriteXml`   | XML       | `xml.etree`                                 |
| `WriteHtml`  | HTML      | `html.parser`                               |
| `WriteSh`    | Shell     | `bash -n` syntax check                      |
| `WriteSql`   | SQL       | `sqlparse`                                  |
| `WriteSvg`   | SVG       | `xml.etree` + root-element check            |
| `WriteDot`   | Graphviz  | `pydot`                                     |

Install the non-stdlib validators with `pip install "vulpcode[docs-tools]"`.

---

## Slash commands

Available inside the REPL:

| Command                    | What it does                                  |
| -------------------------- | --------------------------------------------- |
| `/help`                    | Show all commands                             |
| `/clear`                   | Clear the screen and conversation history     |
| `/exit`                    | Leave the REPL                                |
| `/tools`                   | List enabled tools                            |
| `/cost`                    | Show token usage and estimated cost           |
| `/compact`                 | Compact the conversation to free context      |
| `/provider <name>`         | Switch provider                               |
| `/model <id>`              | Switch model on the current provider          |
| `/save <name>`             | Save the current session                      |
| `/load <name>`             | Restore a saved session                       |
| `/mcp`                     | Inspect connected MCP servers                 |

---

## Permission modes

Vulpcode never executes tools silently by default. Choose a mode that
matches your trust level for the current task:

| Mode      | Flag        | Behavior                                                          |
| --------- | ----------- | ----------------------------------------------------------------- |
| `default` |             | Read tools auto-run; writes and Bash require confirmation         |
| `auto`    | `--auto`    | Auto-approve every tool call                                      |
| `safe`    | `--safe`    | Confirm every tool call, including reads                          |
| `plan`    | `--plan`    | Plan-only — the agent proposes actions but executes nothing       |

Headless mode for scripting:

```bash
vulp --print --auto "refactor src/utils.py to remove duplication"
```

Resume your last session:

```bash
vulp --resume
```

---

## MCP (Model Context Protocol)

MCP servers declared in `~/.vulpcode/config.toml` are launched
automatically. Their tools are added to the registry with the prefix
`mcp__<server>__<tool>` and become available like native tools.

Minimal config:

```toml
[mcp.servers.filesystem]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/home/me/projects"]
```

Inspect runtime state with `/mcp` inside the REPL.

---

## Configuration

Vulpcode reads configuration in this order:

1. CLI flags (`--provider`, `--model`, ...)
2. Environment variables (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`,
   `GEMINI_API_KEY`, `OLLAMA_HOST`, `INTERNAL_LLM_ENDPOINT`, ...)
3. `~/.vulpcode/config.toml`

Sessions, history, and per-project state live under `~/.vulpcode/`.

---

## Status

Alpha (current release: **0.2.0**). The CLI surface, tool set, and config
format may still change before 1.0. See [CHANGELOG.md](CHANGELOG.md) for
release notes.

---

## Documentation

Full documentation, including detailed configuration, recipes, the API
reference, and architecture notes, is built with MkDocs from the `docs/`
directory.

```bash
pip install "vulpcode[docs]"
mkdocs serve
```

---

## Contributing

Issues and pull requests are welcome. To set up a development environment:

```bash
git clone https://github.com/Vulp-Code/vulpcode.git
cd vulpcode
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev,docs,search]"
pytest
ruff check .
mypy
```

---

## License

MIT — see [LICENSE](LICENSE).

---

## Links

- Source code: <https://github.com/Vulp-Code/vulpcode>
- Issues: <https://github.com/Vulp-Code/vulpcode/issues>
- PyPI: <https://pypi.org/project/vulpcode/>
