aa1143/NamiAgent

What it is

NamiAgent is a beginner-oriented tutorial that doubles as a runnable local AI agent. It starts from a 100-line while loop that calls a model, executes tools, and feeds results back into context, then adds one capability per lesson: tools, permissions, context management, skills, chat-app integration, scheduling and heartbeat, MCP, sub-agents, planning, and long-term memory.

The first 11 lessons each ship as a complete, runnable snapshot in lessons/lesson-01 through lesson-11, so you can run the code at any stage or diff adjacent lessons. The final part is article-only: it dissects how mainstream agents such as Claude Code, Codex, Pi, Grok Bot, DeepSeek Harness, OpenClaw, and Hermes are put together, with an overall comparison table (course index, comparison table).

The intended audience is people who want to understand what happens inside an agent rather than adopt a framework. It uses only the openai package, speaks any OpenAI-compatible API, and defaults to DeepSeek. A local web UI shows every model call, tool call, and the full context sent to the model.

Quick start

Requires Python 3.10+. Clone the repository, install dependencies, and point it at a model:

git clone https://github.com/aa1143/NamiAgent.git
cd NamiAgent
pip install -r requirements.txt

export API_KEY=your-model-key
# Optional: switch to another OpenAI-compatible provider
export BASE_URL=https://...
export MODEL=model-name

export NAMI_WORKSPACE=~/agent-workspace   # from lesson 3, the agent can only touch this directory
mkdir -p $NAMI_WORKSPACE

cd lessons/lesson-05
python agent.py

To try the web UI without an API key, run the scripted demo:

cd NamiAgent
python web/app.py --demo

Then open http://localhost:8765. The left panel shows each model call, the model's reasoning text, and tool inputs/outputs; the right panel shows the full context sent each turn (web UI setup). On macOS you can also double-click web/start.command, which creates a virtual environment, installs dependencies, and prompts for an API key (blank input starts demo mode).

Tests run against a fake model and need no API key:

cd lessons/lesson-11 && pytest -q

Requirements and limits

• Python 3.10+ and an API key are needed for real runs. Without a key, use the --demo web mode or the lesson tests from lesson 3 onward.
• Workspace scoping: from lesson 3, NAMI_WORKSPACE limits what the agent can touch. Keep it pointed at a dedicated directory, not your home directory.
• Permission model: file writes and command execution ask for confirmation, but the README states the lesson-3 permission mechanism stops mistakes and cheap boundary violations, not deliberate attacks (security note).
• State and config live outside the workspace: NAMI_STATE_DIR defaults to ~/.nami-agent; MCP server config is ~/.nami-agent/mcp.json from lesson 8; the Telegram bot from lesson 6 needs TG_BOT_TOKEN and TG_ALLOWED_USERS.
• Not production-grade: it is teaching code and not a framework intended to match Claude Code or Codex in features.
• Licensing: code is MIT; articles under docs/ are CC BY-NC 4.0.

HotRepo's take

No GitHub daily rank is recorded for this repository, so the best available signal is the Python new-project list: between 2026-11-01 04:45 and 09:45 UTC it recorded 11 new stars, reaching 113 stars and 8 forks. That is a short five-hour window with no comparison period, which is enough to show early attention but not enough to call a trend. The stronger differentiator is structural: 11 runnable lesson snapshots plus tests that need no API key lower the cost of actually running the code, and the web UI exposes context growth rather than hiding it behind a framework.