Metadata-Version: 2.4
Name: ashcode
Version: 0.1.0
Summary: A terminal coding agent in Python — streaming agentic loop, 12 built-in tools, MCP servers, subagents, and a configurable approval layer.
Author-email: Ashutosh Ranjan <authran.off@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/AuthRan/AshCode
Project-URL: Repository, https://github.com/AuthRan/AshCode
Project-URL: Issues, https://github.com/AuthRan/AshCode/issues
Keywords: agent,cli,coding-agent,llm,mcp,terminal
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Code Generators
Classifier: Topic :: Utilities
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: generated/LICENSE
Requires-Dist: click
Requires-Dist: ddgs
Requires-Dist: fastmcp
Requires-Dist: httpx
Requires-Dist: openai
Requires-Dist: platformdirs
Requires-Dist: pydantic
Requires-Dist: python-dotenv
Requires-Dist: rich
Requires-Dist: tiktoken
Requires-Dist: tomli
Dynamic: license-file

# AshCode

A terminal coding agent in Python — streaming agentic loop, 12 built-in tools, MCP servers, subagents, context compaction, and a configurable approval layer for shell and file operations.

AshCode reads and writes files, runs shell commands, searches the web, and delegates work to scoped subagents — driven by any OpenAI-compatible model endpoint.

![AshCode resolving a single prompt from the terminal](https://raw.githubusercontent.com/AuthRan/AshCode/main/resources/AshCode_singleShot.gif)

## Install

```bash
pip install ashcode
```

Requires Python 3.11+.

## Configure

AshCode talks to any OpenAI-compatible endpoint — OpenRouter, OpenAI, Together, or a local llama.cpp or vLLM server. Create a `.env` in the directory you want to work in:

```ini
API_KEY=your-openrouter-api-key-here
BASE_URL=https://openrouter.ai/api/v1
```

The model must support tool calling.

## Use

```bash
ashcode                                      # interactive session
ashcode "explain the retry logic in this repo"   # single prompt
ashcode --cwd ../other-project               # point it somewhere else
```

Inside an interactive session, `/help` lists the slash commands — switching model or approval policy mid-session, inspecting token usage, saving and resuming sessions, and creating checkpoints.

## What it does

**Agent loop** — fully streaming, parallel tool calls within a turn, a typed event stream that decouples the loop from any renderer, and a configurable turn budget.

**12 built-in tools** — `read_file` `write_file` `edit_file` `apply_patch` with unified-diff previews, `list_dir` `glob` `grep` for navigation, `shell` with timeout and env scrubbing, `web_search` `web_fetch`, and `memory` `todo` for cross-turn state.

**Context management** — automatic compaction into a structured summary at 80% of the window, tool-output pruning outside a protected recent window, and per-turn token accounting.

**Safety** — six approval policies from `on-request` through `yolo`, regex classification of shell commands, mandatory confirmation for writes outside the working directory, and secrets scrubbed from the subprocess environment.

**Extensibility** — MCP servers over stdio and HTTP/SSE, custom tools auto-discovered from `.ai-agent/tools/*.py`, lifecycle hooks around runs and tool calls, and `AGENT.MD` picked up as project instructions.

Configuration is TOML, merged from a user-level file and a project-level `.ai-agent/config.toml`. Secrets stay in `.env` and never enter the config file.

## Writing a custom tool

Drop a Python file in `.ai-agent/tools/` and subclass `Tool`. Note the import path is `ashcode.tools.base` when working against the installed package:

```python
from ashcode.tools.base import Tool
```

Tools are self-describing — declare a Pydantic schema and it is converted to an OpenAI function schema automatically. No change to the agent loop or the prompt is needed.

## Links

- **Source, full documentation and engineering notes:** [github.com/AuthRan/AshCode](https://github.com/AuthRan/AshCode)
- **Video demos:** [reading through a codebase](https://youtu.be/G9MtxyqXOQ0) · [creating and deleting a file](https://youtu.be/DsuoKmBzODU)
- **Issues:** [github.com/AuthRan/AshCode/issues](https://github.com/AuthRan/AshCode/issues)

MIT licensed.
