EduCode Agent

Repository: github.com/3eyedtech-creator/educode-agent

EduCode is a local-first, RAG-aware coding agent CLI. Open any project folder, run educode, and work with your codebase through natural language — ask questions, generate changes, debug failures, and run validation tasks.

It works similarly to Claude Code: the agent indexes your repository, understands context via semantic search, and uses a multi-agent supervisor (planner, coder, reviewer, runner) with human approval before mutating files.

Prerequisites

Before using EduCode, make sure you have:

Optional:

No Docker or separate vector database install is needed — Qdrant runs embedded locally.

Installation

End users (PyPI) — recommended

Install from PyPI with pip:

pip install educode-agent

PyPI normalizes names, so this also works:

pip install educode_agent

For an isolated CLI install (recommended, like Claude Code):

pipx install educode-agent

Verify the educode command is available:

educode --version

If educode is not found, ensure your Python scripts directory is on PATH:

Then open any project folder and start the agent:

cd /path/to/your-project
educode

That launches the interactive chat session (same as educode chat).

From source (developers)

git clone https://github.com/3eyedtech-creator/educode-agent.git
cd educode-agent
poetry install

Verify the CLI:

poetry run educode --version

Environment setup

1. Copy the example env file:

cp .env.example .env

2. Add your OpenAI key to .env or export it in your shell:

# Linux / macOS
export OPENAI_API_KEY=sk-your-key-here

# Windows PowerShell
$env:OPENAI_API_KEY = "sk-your-key-here"

3. (Optional) Set user-level EduCode home — defaults to ~/.educode/:

export EDUCODE_HOME=~/.educode

Quickstart (use in any project)

# 1. Go to your project
cd /path/to/your-project

# 2. One-time setup: create .educode/ and index the codebase
educode init

# 3. Start interactive session (same as `educode chat`)
educode

After init, you should see a header with repo, model, and index info, then:

Ready. Run: educode chat

First-time shortcut

If you skip init, the first educode or educode chat run will auto-initialize the project and index the repository.

Daily usage

Interactive chat (recommended)

cd /path/to/your-project
educode

Or explicitly:

educode chat

Inside the REPL:

Example prompts:

• Where is user authentication handled?
• Add input validation to the login endpoint
• Why is tests/test_users.py failing? Run tests and fix the issue.

One-shot task

Run a single task and exit:

educode run "add pagination to the /users endpoint"

Resume a previous session

Sessions are persisted with a thread_id (Sqlite checkpointer). Resume with:

educode chat --thread-id <your-thread-id>
educode run --thread-id <your-thread-id> "continue previous task"

Global CLI options

These apply to all commands:

educode [OPTIONS] COMMAND [ARGS]...

Options:
  --version          Show version and exit
  -v, --verbose      Enable DEBUG logging
  --model TEXT       Override model (e.g. openai:gpt-4o-mini)
  --repo DIRECTORY   Project root (default: current directory)

Examples:

educode --repo ~/projects/my-api chat
educode --model openai:gpt-4o-mini run "refactor auth middleware"
educode -v chat

Project initialization (educode init)

Creates local EduCode state in your repository:

your-project/
├── src/
└── .educode/
    ├── config.yaml          # per-project settings
    ├── rag_manifest.json    # indexed file hashes
    ├── sessions.db          # session metadata
    └── tasks/               # per-thread checkpoint DBs

init also adds .educode/ to .gitignore when possible.

educode init                  # full init + codebase indexing
educode init --skip-index     # config only, no indexing

Indexing walks your repo (skips node_modules, .venv, __pycache__, etc.), chunks source files, embeds them, and stores vectors in local Qdrant.

Configuration

Project config (.educode/config.yaml)

educode config show
educode config set model=openai:gpt-4o-mini
educode config set token_budget=250000
educode config set auto_approve=false

Common keys:

User config (~/.educode/config.yaml)

User-level settings override defaults and are merged before project config. Use the same keys as project config.

Human approval (safety)

Before writing files or running terminal commands, EduCode asks for approval unless auto_approve=true:

Approve changes? [y/n]

Use y to approve, n to reject. For production work, keep auto_approve=false.

How it works (high level)

1. Index — educode init chunks and embeds your codebase into local Qdrant.
2. Retrieve — During chat/run, the agent calls search_codebase to find relevant code.
3. Plan & execute — A supervisor delegates to planner, coder, reviewer, and runner sub-agents.
4. Persist — Conversation state is checkpointed per thread_id for multi-turn sessions and resume.

Troubleshooting

OPENAI_API_KEY is required

Set the key in your environment or .env:

export OPENAI_API_KEY=sk-...

Or run init/chat with project config strict_api_keys=false (not recommended for production).

Agent does not know my codebase

Re-index the project:

educode init

Ensure files are not in ignored directories (node_modules, .venv, etc.).

Wrong project directory

Pass --repo explicitly:

educode --repo /absolute/path/to/project chat

Verbose logs for debugging

educode -v chat

Development

See DEVELOPMENT.md for copy-paste commands to test locally, verify PyPI releases, and publish new versions.

Quick start:

poetry install --with dev
poetry run pytest tests/unit
poetry run educode --model mock:loop run "test task"

License

MIT — see LICENSE.

Publishing to PyPI (maintainers)

One-time PyPI setup

1. Create an account at pypi.org.
2. Register the project name educode-agent on PyPI (first upload claims it).
3. Enable Trusted Publishing on PyPI for this GitHub repo (recommended):
   • PyPI project → Publishing → Add GitHub Actions publisher
   • Repository: 3eyedtech-creator/educode-agent
   • Workflow: release.yml
   • Environment name: pypi
4. In GitHub repo Settings → Environments, create environment pypi (used by the release workflow).

Release a new version

# 1. Bump version in pyproject.toml and src/educode_agent/__init__.py
poetry version patch   # or minor / major

# 2. Sync __init__.py version manually to match pyproject.toml

# 3. Commit, tag, and push
git add pyproject.toml src/educode_agent/__init__.py
git commit -m "chore(release): bump version to $(poetry version -s)"
git tag "v$(poetry version -s)"
git push origin main --tags

Pushing a v*.*.* tag triggers .github/workflows/release.yml, which runs tests, builds the wheel/sdist, publishes to PyPI, and creates a GitHub Release.

Verify locally before publishing

poetry build
pip install dist/educode_agent-*.whl
educode --version
cd /path/to/a/test/project
educode init --mock-index
educode --model mock:loop run "smoke test"

Manual publish (without GitHub Actions)

poetry build
poetry publish   # requires PYPI_API_TOKEN configured