Metadata-Version: 2.4
Name: kosmos-code
Version: 0.1.0
Summary: AI coding agent that runs in your terminal. Describe what you want to build and Kosmos creates it.
Author: Marilyn Both
License: MIT
Project-URL: Homepage, https://github.com/meryboth/kosmos-cli
Project-URL: Repository, https://github.com/meryboth/kosmos-cli
Project-URL: Issues, https://github.com/meryboth/kosmos-cli/issues
Keywords: cli,ai,coding-agent,openai,llm,developer-tools
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development
Classifier: Topic :: Software Development :: Code Generators
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: openai>=1.0.0
Dynamic: license-file

# Kosmos CLI

AI coding agent that runs in your terminal. Describe what you want to build and Kosmos creates the project for you -- scaffolding, dependencies, code, and a live dev server preview.

## Install

```bash
pip install kosmos-code
```

Or install from source:

```bash
git clone https://github.com/meryboth/kosmos-cli.git
cd kosmos-cli
pip install -e .
```

## Quick start

```bash
# First run will ask you to configure your LLM provider
kosmos

# Or jump straight in with a prompt
kosmos "Create a todo app with React"
```

## Configuration

Kosmos stores your config at `~/.kosmos/config.json`. API keys are saved with restricted file permissions (600).

```bash
kosmos config          # show current provider, model, and masked API key
kosmos config setup    # interactive wizard to set provider + API key
kosmos config model    # change model
kosmos config reset    # remove all stored configuration
```

### Supported providers

| Provider | Models | Get a key |
|----------|--------|-----------|
| **OpenAI** | gpt-5.2, gpt-5-mini, gpt-5-nano, gpt-4.1, gpt-4.1-mini, o3, o4-mini | [platform.openai.com/api-keys](https://platform.openai.com/api-keys) |
| **Anthropic** (via OpenRouter) | claude-opus-4.6, claude-sonnet-4.6, claude-haiku-4.5 | [openrouter.ai/keys](https://openrouter.ai/keys) |
| **Google Gemini** (via OpenRouter) | gemini-2.5-pro, gemini-2.5-flash | [openrouter.ai/keys](https://openrouter.ai/keys) |
| **Groq** | llama-4-scout, gpt-oss-120b, llama-3.3-70b | [console.groq.com/keys](https://console.groq.com/keys) |
| **OpenRouter** | 400+ models from all providers | [openrouter.ai/keys](https://openrouter.ai/keys) |

### Smart model routing

Select **Auto** during setup (the default) and Kosmos picks the best model per task:

| Tier | When | Example (OpenAI) |
|------|------|-------------------|
| Light | Simple edits, installs, running tests | gpt-4.1-nano |
| Standard | Create a component, add a feature | gpt-5-mini |
| Heavy | Build full app, complex debugging | gpt-5.2 |

Tool-calling iterations (reading files, running commands) automatically use the light model to save tokens. Use `--verbose` to see model selection in real time.

## Usage

```bash
kosmos                                     # interactive mode
kosmos "Create a landing page"             # single prompt
kosmos --verbose                           # show token usage and model routing
kosmos --dir ~/my-project "Fix the tests"  # work on an existing directory
```

When you run `kosmos` without `--dir`, you choose:

1. **New project** -- enter a name, pick a stack, start building
2. **Continue existing project** -- pick from `~/Documents/Kosmos/Projects`

### Supported stacks

Python, JavaScript (Node), React (Vite), Next.js, TypeScript (Node), Express API, FastAPI, or describe your own.

## What can Kosmos do?

- **Explore files** -- list directories and read source code
- **Write files** -- create or overwrite any file in the project
- **Run scripts** -- execute `.py`, `.js`, `.ts`, `.sh`, `.rb`, `.go`, `.php`
- **Run shell commands** -- `npm install`, `pip install`, `git init`, etc.
- **Start a dev server** -- launches in background and returns the localhost URL

## Project structure

```
kosmos-cli/
├── main.py            # CLI entry point, agent loop, retry logic
├── prompts.py         # LLM system prompt
├── call_function.py   # Tool dispatcher
├── config.py          # Config storage (~/.kosmos/config.json)
├── providers.py       # LLM provider definitions and client factory
├── cli_config.py      # kosmos config subcommands
├── router.py          # Smart model routing (task classification)
├── functions/
│   ├── get_files_info.py
│   ├── get_file_content.py
│   ├── write_file.py
│   ├── run_file.py
│   ├── run_command.py
│   └── start_server.py
├── pyproject.toml
└── LICENSE
```

## Requirements

- Python >= 3.12
- An API key from any supported provider
- Node.js (optional, for JS/React/Next.js projects)

## License

MIT
