Metadata-Version: 2.4
Name: cozmo-agent
Version: 0.2.0
Summary: CLI AI coding agent: ReAct tools, hybrid RAG, multi-provider LLMs
Project-URL: Homepage, https://github.com/ShashwatXD/cozmo
Project-URL: Repository, https://github.com/ShashwatXD/cozmo
Project-URL: Issues, https://github.com/ShashwatXD/cozmo/issues
Author-email: Shashwat Pratap Singh <singhshashwat.go@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: cli,coding-agent,llm,ollama,openai,rag,react
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
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
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: httpx>=0.27
Requires-Dist: openai>=1.40
Requires-Dist: pydantic-settings>=2.0
Requires-Dist: python-dotenv>=1.0
Requires-Dist: questionary>=2.0
Requires-Dist: rich>=13.0
Requires-Dist: tenacity>=8.2
Requires-Dist: typer>=0.12
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: twine>=5.0; extra == 'dev'
Description-Content-Type: text/markdown

```
          :@@@@@@@@@@@@@=-
         @.              @@@%-=
      @@@                    @@
    @@+  =+  @@@@@@@@@@@+=+: .
   *@@=@@@@%@#%%#****##@@@@@@@*-  @@:=
  @ @@           *@@@@@@#++ ::=*#%  @-=
  @-                 +@@@%*   +*%%* .:-
   @@@@@@@@@@@@@@@@@  @  @@@#*+#%@*+ @.=
 = @%+@@@@@@@@@@@@@@@@@   @#%=+%@+@@@@.+=
 @ @#@@@@@@@@@@@@@@@@@@@ . %#+#@+ #+:@==.
@@ @*@@      @@@@@@@@@@@@-=@#%%@ @ +@+%
@% @=@@      @@@@@@@@@@@@.=@%%@@@@:%-@ %%
%@ @=@@      @@      @@@@ =@%#@*@%@*%@ @%
 - @=@@      @@      @@@@ +@%#@@@@@*%@ @@
   @+@#%%@@@@@@@@@@@@@@@@ +@%%%@.@-%@@@%
   @#@@@@@#@@%%%@%@@@@@@@ +@%%%#.=@#@#
   @@@%%%@%%%@%%@%@@@@%@@-=%%#@+% +=+
      @@@@@@@@@@@@@@@@@@   %%@@*%#
    =@    @@@@@@@@@@@@@  @@@@@*=
      @@@@@*+         -@@@@@@%#  %
      -=#@@@@@@@@@@@@@@@@@@-.  @@@

  ██████╗ ██████╗ ███████╗███╗   ███╗ ██████╗
 ██╔════╝██╔═══██╗╚══███╔╝████╗ ████║██╔═══██╗
 ██║     ██║   ██║  ███╔╝ ██╔████╔██║██║   ██║
 ██║     ██║   ██║ ███╔╝  ██║╚██╔╝██║██║   ██║
 ╚██████╗╚██████╔╝███████╗██║ ╚═╝ ██║╚██████╔╝
  ╚═════╝ ╚═════╝ ╚══════╝╚═╝     ╚═╝ ╚═════╝
```

# Cozmo

CLI coding agent for your repo. One command. Provider setup. Then it indexes and works.

```bash
pip install cozmo-agent
cd ~/your-project
cozmo
```

Requires Python 3.11+.

---

## What happens

1. **Install** `cozmo-agent` (CLI binary is still `cozmo`)
2. Run `cozmo` in any project
3. First run: pick provider → paste key → pick model
4. Cozmo writes config, indexes the repo, opens an interactive session

Type questions at the prompt. Exit with `Ctrl+C` or an empty quit.

```bash
cozmo                # interactive agent (normal use)
cozmo setup          # change provider / model / key
```

---

## Config (where files land)

| Path | What |
|------|------|
| `~/.cozmo/config.json` | Global settings + API key (created on first run) |
| `$XDG_CONFIG_HOME/cozmo/config.json` | Same, if `XDG_CONFIG_HOME` is set |
| `<repo>/.cozmo/` | Index, traces, code graph |
| `<repo>/.cozmo/config.json` | Optional project overrides |

```bash
cozmo config         # print exact paths
cozmo config --show  # print JSON (key masked)
cozmo doctor         # effective settings
```

<details>
<summary>Example <code>~/.cozmo/config.json</code></summary>

```json
{
  "provider": "openai",
  "model": "gpt-4o-mini",
  "api_key": "sk-...",
  "allow_write": true,
  "allow_shell": false,
  "max_agent_steps": 8
}
```

Load order: CLI flags → `COZMO_*` env → cwd `.env` → project config → global config → defaults

</details>

---

## Commands

| | |
|--|--|
| `cozmo` | Interactive agent (default) |
| `cozmo setup` | Interactive reconfigure |
| `cozmo config` | Config paths |
| `cozmo index` | Force re-index |
| `cozmo chat` | LLM only, no tools |
| `cozmo doctor` | Diagnose settings |
| `cozmo -m "…"` | Optional one-shot (no REPL) |

---

## Stack (short)

- Owned ReAct loop (no LangChain)
- Tools: read/write, search, semantic search, git, symbols, graphs (shell gated)
- Hybrid RAG: BM25 + embeddings
- Providers: OpenAI, OpenRouter, Ollama, any OpenAI-compatible API

```
cozmo → config → index → AgentRunner
              LLM ↔ tools ↔ your files
```

---

## Dev

```bash
git clone https://github.com/ShashwatXD/cozmo.git
cd cozmo
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest -q
```

---

**Fun fact:** Named after [Anki Cozmo](https://www.digitaldreamlabs.com/pages/cozmo), the robot pet I always wanted. Learning project, not affiliated. PyPI package is `cozmo-agent`.

MIT
