code-cli/USAGE.md

# Engineering Agent CLI Guide

## Overview
- The CLI now exposes a single Gemini/Qwen-style agent session.
- The agent reads, edits, and tests files inside your project using tools such as `read_file`, `write_file`, `edit_file`, `search_files`, and `run_cmd`.
- Conversation history is preserved in-memory, so consecutive prompts keep their context.

## Running
1. Activate your environment (optional) and execute `python main.py`.
2. Provide the project root when prompted, or press Enter to use `generated_project`.
3. Optional flags:
   - `--backend {groq|gemini|openrouter}`
   - `--model MODEL_NAME`
   - `--temperature 0.2`
   - `--no-auto-context`
   - `--project-directory /path/to/project`
   - `--recursion-limit 200`
4. Once the REPL opens, type requests such as `agent> Add pytest coverage to the auth service`.

## CLI Commands
- `:help` or `:h` -> Show the built-in commands.
- `:context` -> Refresh and print the workspace summary.
- `:clear` -> Reset the conversation history.
- `:history` -> Display the latest user/agent turns.
- `:exit`, `:quit` -> Leave the CLI (`exit` as plain text also works).

## Expected Behaviour
- The agent inspects existing files before editing and lists the tools it uses.
- After risky or large edits it runs `pytest`, `npm test`, `go test ./...`, etc. through `run_cmd` and reports the output.
- Replies stay concise and reference the files that changed.
- Only the registered tools are available; commands like `repo_browser.*` will fail.

## Tips
- For multi-package repos, run separate sessions per package to keep summaries targeted.
- Because edits happen in-place, review and commit changes under version control after each session.
- Use `:context` to rescan the repo whenever you add/remove files outside the agent.