Metadata-Version: 2.4
Name: codegopher
Version: 0.1.0
Summary: A Python-native, provider-agnostic AI coding agent for your terminal
Project-URL: Homepage, https://github.com/shamitv/codegopher
Project-URL: Documentation, https://codegopher.readthedocs.io
Project-URL: Repository, https://github.com/shamitv/codegopher
Project-URL: Issues, https://github.com/shamitv/codegopher/issues
License: Apache-2.0
License-File: LICENSE
Keywords: agent,ai,cli,coding,llm,terminal
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
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 :: Terminals
Requires-Python: >=3.11
Requires-Dist: click>=8.1
Requires-Dist: httpx>=0.27
Requires-Dist: mcp>=1.27.1
Requires-Dist: openai>=2.37.0
Requires-Dist: pydantic>=2.7
Requires-Dist: rich>=13.7
Requires-Dist: textual>=8.2
Requires-Dist: tiktoken>=0.7
Requires-Dist: tomlkit>=0.13
Provides-Extra: dev
Requires-Dist: hatch>=1.12; extra == 'dev'
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest-httpx>=0.30; extra == 'dev'
Requires-Dist: pytest-mock>=3.14; extra == 'dev'
Requires-Dist: pytest>=8.2; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Provides-Extra: sandbox
Requires-Dist: docker>=7.0; extra == 'sandbox'
Description-Content-Type: text/markdown

# CodeGopher

> A Python-native, provider-agnostic AI coding agent for your terminal.

CodeGopher includes both the original headless command and an interactive Textual TUI for iterative project work. It can stream through OpenAI Chat Completions or Responses API, connect configured MCP stdio/SSE servers as approval-gated tools, expand file mentions, manage context, compact long sessions, save memory, load Markdown skills, track session TODOs, and resume local terminal sessions.

## Usage

```bash
cgopher
cgopher -p "What does this project do?"
cgopher --no-project-init -p "What does this project do?"
cgopher -p "read this test log and summarize it" < test.log
cgopher init
cgopher init --skill-pack repo-docs
cgopher init --skill-pack security
```

Run plain `cgopher` in an interactive terminal to open the TUI. Use `-p/--prompt` for the headless one-shot path.
On first use in a project, CodeGopher creates default local project guidance under `.codegopher/skills/project/SKILL.md`; pass `--no-project-init` to disable that for a run.
Run `cgopher init [PATH]` to create default project-local Markdown skill guidance under `.codegopher/skills`.
Use `cgopher init [PATH] --skill-pack repo-docs|security|all` to materialize built-in repository documentation and static security review skills into a project.

Useful flags:

- `--model`, `--provider`, and `--base-url` override model/provider settings.
- `--api-family chat_completions|responses` selects the OpenAI-compatible Chat Completions path or OpenAI Responses API path for the run.
- `--approval-mode review|auto|yolo` controls tool approval behavior.
- `--no-project-init` disables first-use project guidance creation for the current run.
- `--json` emits machine-readable headless results.
- `--debug` shows provider reasoning content in headless text output when available.

## Interactive TUI

The Textual TUI keeps chat history, streams assistant answers, renders tool calls/results, and shows inline approval prompts. Local session history is saved under CodeGopher's user data directory and automatically resumes for the same project directory.

Slash commands:

- `/help`: show commands.
- `/clear`: clear visible chat history without deleting saved session data.
- `/compact [instructions]`: summarize older provider context while preserving recent turns.
- `/forget ID --yes`: delete a saved memory after confirmation.
- `/memory`: list session and project memories.
- `/model [NAME]`: show or update the active model.
- `/mode [review|auto|yolo]`: show or update approval mode.
- `/stats`: show session counters.
- `/shell COMMAND`: run a shell command after approval unless `yolo` is active.
- `/skills [load ID]`: list or explicitly load Markdown skills.
- `/todo`, `/todo add TEXT`, `/todo done ID`: manage session TODO state.

Prompt helpers:

- `@path`, glob-style mentions such as `@src/**/*.py`, and `@glob:pattern` expand readable text files into the submitted prompt.
- `@skill:ID` explicitly loads a discovered Markdown skill into provider context.
- Mention expansion respects project boundaries and `.codegopherignore`.
- Models that emit `reasoning_content` show thinking separately from final answer text; TUI reasoning is collapsed by default.

Context, memory, skills, and TODOs:

- `/stats` reports context token usage when a provider `context_window` is configured.
- Automatic compaction runs before a turn would exceed the configured threshold; manual `/compact` is always visible in chat.
- `save_memory` stores approved session or project memories under CodeGopher's user data directory, with secret-like values redacted.
- Project skills live in `.codegopher/skills/*/SKILL.md`, user skills live in `~/.codegopher/skills/*/SKILL.md`, and built-in skills ship with the package.
- Built-in v0.5 skill packs include `repo-domain-docs`, `repo-tech-docs`, and `crud-owasp-static-audit`; the security skill is static-only and does not perform live probing, fuzzing, credential attacks, dynamic scanners, exploit payloads, or network tests.
- Active TODOs are included in provider context and can also be updated by the model through the `update_todo` tool.

MCP tools:

- Configure MCP servers in settings under `[mcp.servers.NAME]`.
- `transport = "stdio"` starts a local MCP server process with `command`, `args`, optional `env`, `cwd`, and `startup_timeout_seconds`.
- `transport = "sse"` connects to an SSE MCP endpoint with `url`, optional `headers`, `headers_env`, `timeout_seconds`, and `sse_read_timeout_seconds`.
- MCP tools are exposed as `mcp__SERVER__TOOL`, always require approval, and are cleaned up after headless runs or TUI exit.
- SSE header values and values resolved from `headers_env` are not printed or persisted.

## Implemented Features

- Headless Click CLI via `codegopher`, `cgopher`, and `python -m codegopher`.
- Interactive Textual TUI for repeated terminal sessions.
- Pydantic settings with CLI, environment, project, user, and default precedence.
- OpenAI-compatible Chat Completions streaming provider with streamed tool-call and reasoning parsing.
- OpenAI Responses API streaming provider with stateless local replay of required response output items.
- MCP stdio/SSE tool discovery and approval-gated execution through the official Python MCP SDK.
- Approval-aware file and shell tools with prior-read and parent-inspection gates.
- Context-window accounting, manual/automatic compaction, memory, Markdown skills, session TODOs, slash commands, file mentions, shell passthrough, and local session save/resume.
- JSON output for automation and focused unit/integration test coverage.

## Development

Install the package with development tools:

```bash
pip install -e ".[dev]"
```

Useful Hatch scripts:

```bash
hatch run test
hatch run lint
hatch run typecheck
```

## Planned Direction

- Sub-agents, advanced coding workflows, and sandboxing remain future roadmap items.
- Provider capability checks will expand as more provider families are added.
- Git/worktree helpers and richer initialization workflows may expand after the v0.3 release.

## Docs

- [Product Intro](docs/product/INTRO.md)
- [Product Roadmap](docs/product/ROADMAP.md)
- [Initial v0.1 Plan](docs/plans/initial/PLAN.md)
- [llama.cpp OpenAI-Compatible Test Endpoint](docs/devguide/llm/LLAMA_CPP_OPENAI_ENDPOINT.md)
- [VS Code Extension Testing](docs/devguide/vscode/TESTING.md)

## Configuration

CodeGopher uses `~/.codegopher/settings.toml` for user-wide settings and `.codegopher/settings.toml` for per-project settings. CLI flags and environment variables take precedence.

```toml
[model]
provider = "openai"
name = "gpt-4o"

[[providers.openai]]
id = "gpt-4o"
name = "GPT-4o"
api_key_env = "OPENAI_API_KEY"
api_family = "chat_completions"
```

For OpenAI Responses API, set `api_family = "responses"` or pass `--api-family responses`. Responses calls use `store = false`; CodeGopher keeps the required replay metadata locally.

For OpenAI-compatible local endpoints, set `base_url` on the provider entry and export a key through the configured `api_key_env`.

```toml
[mcp.servers.playwright]
enabled = true
transport = "stdio"
command = "npx"
args = ["@playwright/mcp@latest", "--headless", "--isolated"]

[mcp.servers.remote_docs]
enabled = true
transport = "sse"
url = "https://example.test/sse"
headers_env = { Authorization = "MCP_REMOTE_DOCS_AUTHORIZATION" }
timeout_seconds = 5
sse_read_timeout_seconds = 300
```

## License

Apache-2.0
