HarnessLingo
zongyu0523/HarnessLingo
Agent completo para aprendizado de idiomas com NPCs e repetição espaçada
Ver no GitHubAgent de aprendizado de idiomas construído com arquitetura de Harness Engineering, oferecendo prática em cenários com NPCs, quiz inteligente, revisão espaçada e biblioteca de vocabulário estruturada. Sistema completo com subagentes, gates human-in-the-loop e cache otimizado de prompts.
Instalação
npx convez-ai zongyu0523/HarnessLingo1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Praticar conversas reais com NPCs em cenários realistas
- Gerenciar vocabulário e padrões de sentença com análise semântica
- Revisar conteúdo com quiz de múltipla escolha, flashcards e ditado
Veredito

Projeto robusto de agent com arquitetura sofisticada (subagentes, DAG de tarefas, consolidação de memória). Ideal para quem quer entender padrões de design de agents em escala, mas requer investimento técnico significativo para customização além do escopo de aprendizado de idiomas.
README
A tradução para o português deste README ainda está na fila.
HarnessLingo
This is not a ChatGPT wrapper. It's a complete agent infrastructure — with strict tool permissions, background subagents, human-in-the-loop gates, and optimized prompt caching — purpose-built to help users learn languages reliably and at scale.
Features
Vocabulary & Sentence Library — Save words and sentence patterns with phonetics, examples, synonyms, collocations, and native-language translations. Stored as structured JSON — searchable, filterable, and exportable. Clickable badges (synonyms, antonyms, collocations) jump to AI chat for instant exploration.
Scenario Practice (Subagent NPC Role-Play) — Practice real conversations with an AI character powered by a background subagent. The NPC stays in character, tracks your task completion through a dependency graph (DAG), and weaves corrections into natural dialogue — never breaking character to teach.
Quiz & Review System — Three quiz modes at zero API cost: Choice (multiple-choice from entry data), Flashcard (flip & self-assess with "I know" / "I don't know"), and Spell (type the word from a meaning + first-letter hint). Mixed mode blends all three. Per-entry quiz stats (quiz_correct_count / quiz_wrong_count) track performance independently from spaced repetition.
On-Demand Skill System — Create your own custom skills or load specialized expert knowledge (IELTS prep, business emails, grammar coaching) on demand. Just drop a Markdown file into the skills folder — the system auto-discovers it with zero code changes. Users can build and share skill packs for any learning domain.
Long-Term Memory — The agent remembers your learning preferences, error patterns, and goals across sessions. A background consolidator merges duplicates and prunes stale entries, while protecting memories you explicitly saved.
Multi-Language Support — Learn any language — English, Japanese, Korean, etc. TTS pronunciation adapts to the learning language automatically. The agent detects your message language and replies accordingly.
Spaced Repetition — Entries follow a [1, 2, 3, 7]-day review schedule. After 5 successful reviews, an entry graduates. A background heartbeat job checks for due entries every hour.
Quick Start
git clone https://github.com/zongyu0523/HarnessLingo.git
cd HarnessLingo
Docker (recommended):
docker-compose up --build -d
Local development:
pip install -r requirements.txt
cd ui && npm install && npm run build && cd ..
uvicorn api.main:app --host 0.0.0.0 --port 8000
Open http://localhost (Docker) or http://localhost:8000 (local).
Setting Up Your API Key
HarnessLingo uses the Anthropic API — bring your own key.
- Get a key at console.anthropic.com → API Keys.
- Connect it in the app: Settings → paste under Anthropic → Connect. The app verifies before saving.
What does it cost?
Pure conversation, with prompt cache working:
| Usage | Sonnet 4.6 | Haiku 4.5 |
|---|---|---|
| Single reply | ~$0.01 | ~$0.002 |
| 10-turn session | ~$0.08 | ~$0.02 |
| Daily practice (monthly) | ~$6 | ~$1.50 |
The token badge in the header tracks your usage in real time. Typical daily language practice tends to stay within the cost of a Claude Pro subscription ($20/month), and you can mix models per role (Haiku for background, Sonnet for chat) to push costs lower.
🧪 Multi-model support is in testing. OpenAI, Gemini, and Ollama providers are coming soon — background subagents will run on cheaper models (Gemini Flash, local Ollama) to push costs even lower.
Privacy
Your key lives in your browser's localStorage and is sent only to Anthropic — never to our backend, never logged. Click Remove in Settings to wipe it.
Architecture Deep Dive
Why Harness Engineering
In 2024, everyone was doing Prompt Engineering — telling the AI what to say. In 2025-2026, the frontier shifted to Harness Engineering — building the roads, guardrails, and traffic systems that let AI agents drive safely.
The AI model is a powerful horse. The harness is the saddle, reins, and bit. This project is the harness.
This project extracts the core architectural patterns of AI agents and rebuilds them for a language learning domain. The result is a system where:
- Every agent has exactly the tools it needs — no more, no less
- Sensitive actions require human approval before execution
- Background subagents handle slow tasks without blocking the conversation
- The system prompt is engineered for cache efficiency, not just correctness
Below are the five pillars of this harness.
1. Tool Orchestration & Least-Privilege
Claude Code gives its agent generic tools — Read, Write, Edit, Grep, Bash. These are powerful because they can interact with any codebase. But for a language learning domain, generic tools are dangerous and imprecise.
I took the same tool-use pattern and built domain-specific tools with built-in constraints:
Base Tool Mapping: Claude Code → HarnessLingo
| Claude Code | HarnessLingo | What Changed |
|---|---|---|
Grep — search codebase | search | Searches vocabulary + sentence entries by query, type, language |
Read — read file contents | read | Reads a specific entry by ID, returns structured card data |
Write — create file | write | Creates vocabulary/sentence entries with auto-generated spaced-repetition metadata, UUID, timestamps |
Edit — modify file | update | Patches specific fields on an existing entry (e.g., add a synonym, change level) |
AgentTool — spawn subagent | sessions_spawn | Fire-and-forget dispatch with async bus callback (non-blocking) |
SkillTool — load skill | load_skill | Two-layer on-demand knowledge loading |
The key insight: a write tool that can only create vocabulary entries is safer than a Write tool that can create any file. The tool's constraints ARE the product logic — schema enforcement, spaced-repetition initialization, and category linking happen inside the tool, not in the prompt.
Domain-Only Tools (No Claude Code Equivalent)
| Tool | Purpose |
|---|---|
categories | Organize entries into groups |
save_memory / delete_memory / search_memory | Long-term memory with source-based access control |
generate_quiz | Zero-token quiz generation — no LLM call, questions built from entry data |
save_scenario | Create practice scenarios with NPC persona + task dependency graph |
save_exam | AI-generated exams with detailed explanations |
complete_task / update_task | Track scenario progress (scenario agent only) |
Strict Per-Agent Tool Access
Not every agent sees every tool. Each agent receives only the tools it needs — this is least-privilege applied to LLM agents.
Beyond tool filtering, the system also distinguishes each agent's execution mode and visibility:
| Agent | Tools | Execution | Visibility |
|---|---|---|---|
| Main Agent | search, read, write, update, categories, sessions_spawn, memory ops, generate_quiz, load_skill | Foreground, streams to WebSocket | User talks directly |
| Scenario NPC | complete_task, update_task | Foreground, separate session | User interacts on scenario page |
| memory_extractor | save_memory | Background, silent | Invisible to user, auto-triggered after 5+ turns |
| memory_consolidator | save_memory, delete_memory, search_memory | Background, silent | Invisible to user, auto-triggered every 24h |
| scenario_builder | save_scenario | Background, notifies on completion | User receives "Scenario ready!" notification |
| exam_builder | save_exam | Background, notifies on completion | User receives "Exam ready!" notification |
Background subagents are dispatched via asyncio.create_task — non-blocking to the main conversation. On completion, results are delivered through a bus queue into the parent session, and the frontend receives a notify event.
The system also implements source-based protection — system subagents (source=auto) cannot delete memories the user explicitly saved (source=agent). This rule is enforced at the store layer.
2. Multi-Agent Topology
The system runs three types of agents. All share the same run_agent() loop — an async generator that yields typed events — but with different tools, prompts, and lifecycles.
Main Agent (Interactive)
The primary conversational agent. Has access to all user-facing tools. Streams responses in real-time via WebSocket. Persists every turn to session storage.
Scenario Agent (NPC Role-Play)
A separate agent that takes on a character identity (e.g., "You are a barista at a coffee shop"). It only has complete_task and update_task — it tracks whether the user demonstrates specific language skills through natural conversation, never breaks character, and never teaches explicitly.
Each scenario includes a task dependency graph (DAG) — tasks can have prerequisites and subtasks. The NPC steers conversation toward incomplete tasks naturally.
Subagents (Background Workers)
Subagents are registered as SubagentDef dataclasses and auto-discovered at startup. They come in two flavors:
User-level (dispatched by the main agent via sessions_spawn):
scenario_builder— creates practice scenarios from a topic descriptionexam_builder— generates AI-written exams with explanations
System-level (auto-triggered, invisible to user):
memory_extractor— analyzes conversation after 5+ turns, extracts learning patternsmemory_consolidator— runs every 24h, merges duplicates, prunes stale memories
Why Fire-and-Forget Instead of Nested Loops
Claude Code's AgentTool spawns a nested query() loop and blocks until the subagent finishes. This works for fast tasks like file search.
We chose a different pattern: fire-and-forget with bus-based result delivery.
Main Agent calls sessions_spawn("Build a coffee shop scenario", "scenario_builder")
→ tool returns {"status": "accepted"} immediately
→ main agent continues the conversation
→ subagent runs in background (separate asyncio.Task)
→ on completion, result goes to ANNOUNCE_QUEUE
→ bus flusher injects result into parent session
→ WebSocket sends notify event to frontend
→ user sees "Scenario ready!" notification
Why? Language learning subagents are slow — building a scenario requires multiple LLM calls. Blocking the conversation for 30+ seconds would destroy the user experience.
3. Prompt Harness & Skill System
4-Block System Prompt Assembly
The system prompt is not a single monolithic string. It's assembled from 4 blocks, each with a distinct stability profile:
| Block | Content | Stability | Cache Impact |
|---|---|---|---|
| Block 1: Identity | "You are HarnessLingo, a {lang} learning assistant." | Stable across session | High cache hit |
| Block 2: Tool Guide | Assembled from each tool's USAGE_GUIDE string | Varies by agent type | Semi-stable |
| Block 3: Agent Rules | Behavioral constraints + available subagents + skills | Per-session | Semi-stable |
| Block 4: Memory Rules | save/search/delete instructions + staleness markers | Optional (excluded for subagents) | Stable |
Critical design decision: Memory content is NOT in the system prompt. It's injected into messages[0] as a <memories> block. This keeps the system prompt stable for KV cache — if memory were in the system prompt, every new memory would invalidate the entire cache prefix.
This is directly inspired by Claude Code's prompt caching strategy — both systems use cache_control breakpoints to maximize KV cache reuse across turns.
Two-Layer Skill System
Skills are specialized knowledge bundles (e.g., "IELTS preparation", "business email patterns"). Loading all skills into the system prompt would waste context on knowledge that may never be needed.
Layer 1 — Always loaded (cheap): Skill names and one-line descriptions are listed in the system prompt. The agent knows what skills exist. Cost: ~50 tokens per skill.
Layer 2 — On-demand (via tool_result):
When the agent calls load_skill("ielts"), the full skill body is returned in the tool result — injected into context only when actually needed. Cost: hundreds to thousands of tokens, but only when relevant.
This mirrors Claude Code's deferred tool loading (ToolSearch) — don't pay the context cost for capabilities you might not use.
Skills are auto-discovered from agent/skills/*/SKILL.md files with YAML frontmatter. To add a new skill, drop a file — no code changes needed.
4. Memory System (Read / Write / Update)
The agent has long-term memory that persists across sessions. The system is split into three distinct operations, each with its own mechanism:
Read — Session-Start Injection
When a session begins, all memories are loaded from the store and injected into messages[0] as a <memories> block — not into the system prompt. This is a deliberate cache optimization: the system prompt stays stable for KV cache, while memory content rides in the message layer.
Each memory carries a staleness marker based on age:
- No marker — fresh, trustworthy
[OLD](>7 days) — may be outdated, verify before acting[STALE](>30 days) — likely outdated, confirm with user first
The agent can also call search_memory to query memories by type or date mid-conversation.
Write — Dual-Path Memory Creation
Memories are created through two paths:
Path 1: Explicit save — The agent calls save_memory when it detects a pattern worth remembering (user states their level, corrects behavior, shows a recurring error). Each save: type + description (max 120 chars) + tag. Batch up to 3 per call. The agent is instructed to save silently — no "I've saved that to memory" announcements.
Path 2: Auto-extraction — A background memory_extractor subagent is dispatched automatically when:
- 5+ turns have passed since the last save
- 5+ user messages since the last extraction
- No extraction already in progress
The extractor analyzes the recent conversation and saves observations the main agent missed. It also runs force_extract on WebSocket disconnect (lower threshold: 2+ messages) to capture insights from short sessions.
Every memory is tagged with a source field:
agent— explicitly saved during conversation (user-initiated or agent-observed)auto— saved by the memory_extractor subagentmerged— created by the consolidator from multiple memories
Update — Background Consolidation
A memory_consolidator system subagent runs every 24 hours when >10 memories exist. It:
- Deletes low-quality
source=automemories (too vague, based on guesses, single-occurrence) - Merges overlapping memories into a single condensed entry
- Resolves contradictions (newer wins)
- Leaves standalone high-quality memories untouched
Source protection: The consolidator (source=merged) cannot delete source=agent memories. The delete_memory tool enforces this at the store layer — if a system caller tries to delete a user-created memory, it returns protected instead of deleting. This ensures the system never erases something the user explicitly asked to remember.
The consolidator runs silently — no notification, no bus event, no user-visible output.
5. Human-in-the-Loop & Observability
Confirmation Gate
Sensitive tools require explicit user approval before execution. When the agent calls a gated tool:
- The loop yields a
confirm_requestevent with a human-readable summary - The frontend shows an approval dialog
- The user clicks Allow or Deny
- The decision resolves an
asyncio.Futurein the agent loop - The tool executes (or returns a denial message to the LLM)
Timeout: 120 seconds. Default on timeout: deny.
Currently gated tools: delete_memory, save_exam, load_skill. The gate is configurable — adding a new tool to the confirmation list requires one line in confirm_config.py.
Token Observation Engine
Every LLM call — whether from the main agent, scenario NPC, or background subagents — is intercepted, normalized, and priced in real-time.
The system consists of three layers:
1. Token Tracker (token_tracker.py)
- Normalizes raw Anthropic usage objects into a standard
NormalizedUsageformat - Calculates USD cost using a built-in pricing table (supports Claude Sonnet, Opus, Haiku with fuzzy model-version matching)
- Maintains per-session running totals (input tokens, output tokens, cache read/write, cumulative cost)
- Supports batch mode — multiple concurrent LLM calls (e.g., card generation) are buffered and emitted as a single combined event
2. Diagnostic Event Bus (diagnostic.py)
- A global pub/sub system for observability events (separate from the subagent result bus)
- Supports both sync listeners (for file logging) and async listeners (for WebSocket push)
- Every
model.usageevent flows through this bus to reach all subscribers simultaneously - Includes recursion guards and crash-safe listener isolation
3. Frontend Token Badge
- A
useTokenUsagehook subscribes tousageWebSocket events and tracks per-session totals - A
TokenBadgecomponent displays real-time cost, turn count, and total tokens inline in the chat header - Format:
$0.0042 · 3 turns · 12,450 tokens
The pipeline: LLM response → record_usage() → diagnostic bus → emit_async() → JSONL file log + WebSocket broadcast → frontend badge update. All within the same event loop tick.
A diagnostic_heartbeat job also fires periodically, emitting a system-wide snapshot of all active session accumulators.
Error Recovery
The loop tracks consecutive tool failures. After 3 consecutive errors, it force-stops with a user-facing message instead of burning tokens on a confused retry loop.
Inspired By
An AI agent inspired by the goal of learning a new language — built by studying the harness engineering patterns behind Claude Code and OpenClaw.
Roadmap
Features currently in active development:
| Feature | Description | Status |
|---|---|---|
| Multi-model support | Support OpenAI, Gemini, and Ollama alongside Anthropic. Lets users pick cheaper tiers (Gemini Flash) or run fully local (Ollama) — background subagents can run on low-cost models to reduce total spend. | 🧪 In testing |
| Scenario voice system | Voice input (STT) + natural TTS output for scenario role-play. Practice pronunciation and listening comprehension, not just text-based conversation. | 📋 Planned |
| Web search & article crawler | Search the web for real-world articles, news, and example sentences. Auto-extract vocabulary from crawled content and add to your library — learn from authentic materials, not textbook examples. | 📋 Planned |