Metadata-Version: 2.5
Name: fj-agent
Version: 0.1.0
Summary: A small, readable coding agent for learning how agents work
Requires-Python: >=3.11
Requires-Dist: httpx<1,>=0.28
Requires-Dist: python-dotenv<2,>=1
Description-Content-Type: text/markdown

# fj

A tiny coding agent with OpenRouter model support.

## Quickstart

Create an [OpenRouter API key](https://openrouter.ai/settings/keys) and copy the
environment template:

```bash
cp .env.example .env
```

Set `OPENROUTER_API_KEY` in `.env`, then run:

```bash
uv run fj
```

`fj` automatically reads `.env` from the current directory. Exported environment
variables take precedence.

The default model is `openrouter/free`.

## Other usage

```bash
uv run fj "Explain the agent loop in this repository"

uv run fj --resume

uv run fj --workspace examples/buggy_calculator --yolo \
  "Fix the failing tests and run them"

uv run fj --help
```

Interactive commands: `/help`, `/reset`, `/exit`. Ctrl-C stops the current turn. Ctrl-D exits.

## What it can do

| Tool | Behavior |
| --- | --- |
| `list_files` | Find files using a glob, such as `**/*.py` |
| `read_file` | Read UTF-8 text with line numbers and a line range |
| `search_files` | Search file contents for a literal string |
| `write_file` | Create or overwrite a file after showing a diff |
| `edit_file` | Replace one exact, unique piece of text after showing a diff |
| `run_shell` | Run tests or commands, returning output and the exit code |

The root `AGENTS.md`, if present, is included as project instructions.
