Metadata-Version: 2.4
Name: learncode-agent
Version: 0.1.0
Summary: A terminal coding tutor that scaffolds a project and tests, then makes you write the core logic.
Author: Wesley Allen
License: MIT
Project-URL: Homepage, https://github.com/Wesley-Allen-01/LearnCode
Project-URL: Repository, https://github.com/Wesley-Allen-01/LearnCode
Project-URL: Issues, https://github.com/Wesley-Allen-01/LearnCode/issues
Keywords: learning,tutor,agent,cli,openai,education
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Education
Classifier: Topic :: Software Development
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: docstring-parser>=0.18.0
Requires-Dist: openai>=2.0.0
Requires-Dist: prompt-toolkit>=3.0.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: rich>=14.0.0

# LearnCode

A terminal coding tutor that makes **you** write the hard parts.

Copilot and Cursor are great at writing code *for* you. LearnCode is built around the opposite goal: when you want to actually learn a project — by typing it out, debugging it, and getting feedback — it scaffolds everything around the core logic and leaves the interesting functions as `NotImplementedError` stubs for you to fill in. Then it reviews what you wrote.

> Status: early. Working end-to-end for Python projects with the OpenAI API. Issues and feedback welcome.

## Demo

_A short asciinema cast of a real session is coming. For now, the flow below is the fastest way to picture it._

## How it works

LearnCode is a single CLI with five modes. You move through them in order; each mode hands the next one the artifacts it needs.

1. **Brainstorm** — asks what you want to build, your background, and the language. Helps you pick a project with real core logic to implement. Produces a one-page Project Brief.
2. **Plan** — takes the brief and designs a build plan: what plumbing the agent will write, and what TODO functions you will write. Each TODO has a typed signature, plain-English behavior, examples, edge cases, and a difficulty.
3. **Problem Designer** — creates the project directory, writes the plumbing (entry points, I/O, config, helpers), drops each TODO function as a stub, and writes a test file with one test per behavior. Never writes the body of a TODO — that's your job.
4. **Build** — a general-purpose coding agent for anything you ask afterwards. Implements changes, runs read-only commands, asks for approval on file writes.
5. **Critic** — reviews the functions you implemented. Direct, specific, unsycophantic feedback on correctness, edge cases, clarity, and whether the implementation matches the plan.

Switch modes with `shift+tab` (cycle) or `/<mode>` / `/mode <name>` (jump).

## Install

Requires Python 3.11+ and an OpenAI API key.

```bash
git clone https://github.com/Wesley-Allen-01/LearnCode.git
cd LearnCode
uv sync
```

Put your key in a `.env` file in the project directory, or export it:

```bash
echo "OPENAI_API_KEY=sk-..." > .env
# or
export OPENAI_API_KEY=sk-...
```

Then run:

```bash
uv run learncode-agent
```

> `pipx install learncode-agent` is coming once `0.1.0` is on PyPI.

You can override the model with `LEARNCODE_MODEL` (default: `gpt-4.1-mini`).

## Commands and shortcuts

Inside the TUI:

| Command / key       | What it does                                    |
| ------------------- | ----------------------------------------------- |
| `/help`             | Show the full command list                      |
| `/<mode>`           | Jump to `brainstorm`, `plan`, `problem_designer`, `build`, or `critic` |
| `/mode <name>`      | Same, longer form                               |
| `shift+tab`         | Cycle to the next mode                          |
| `pgup` / `pgdn`     | Scroll the transcript (mouse wheel works too)   |
| `ctrl+home` / `ctrl+end` | Jump to top / bottom of the transcript     |
| `quit` or `q`       | Exit                                            |
| `ctrl+c` / `ctrl+d` | Exit immediately                                |

File changes and shell commands always ask for approval before running.

## A typical session

1. Start in **Brainstorm** — chat about what you want to build until you confirm a project.
2. It auto-advances to **Plan**. Read the plan, request changes, approve it.
3. It auto-advances to **Problem Designer**. The agent creates the project, fills in the plumbing, and tells you which functions to implement and how to run the tests.
4. You implement the TODO functions in your editor.
5. Switch to **Critic** with `/critic` to get focused review. Iterate.
6. Use **Build** with `/build` for any general code change you'd like the agent to make.

## Project layout

```
learncode_agent/
  main.py             # mode orchestration, streaming, handoff parsing
  tui.py              # prompt_toolkit TUI
  tools.py            # file tools + approval gating
  terminal_style.py   # ANSI helpers
  prompts/            # one system prompt per mode
tests/                # unit tests
```

## Roadmap

Concrete things on deck:

- Publish `0.1.0` to PyPI so install is `pipx install learncode-agent`.
- Multi-provider support (Anthropic, local Ollama) so you don't need an OpenAI key.
- Session persistence so you can resume a project across runs.
- A web-search tool for Build/Critic.
- A small library of starter projects.

Issues are the best way to push priorities: https://github.com/Wesley-Allen-01/LearnCode/issues

## License

MIT.
