convez.ai
AgenteProdutividadeAvançado
zongyu0523

HarnessLingo

zongyu0523/HarnessLingo

Agent completo para aprendizado de idiomas com NPCs e repetição espaçada

Ver no GitHub
InicialPluginScore · de 0 a 100

Agent 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/HarnessLingo

1 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

Estrelas
1
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 6 meses
Versão
—
Issues abertas
0
Contribuidores
1

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.

  1. Get a key at console.anthropic.com → API Keys.
  2. 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:

UsageSonnet 4.6Haiku 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 CodeHarnessLingoWhat Changed
Grep — search codebasesearchSearches vocabulary + sentence entries by query, type, language
Read — read file contentsreadReads a specific entry by ID, returns structured card data
Write — create filewriteCreates vocabulary/sentence entries with auto-generated spaced-repetition metadata, UUID, timestamps
Edit — modify fileupdatePatches specific fields on an existing entry (e.g., add a synonym, change level)
AgentTool — spawn subagentsessions_spawnFire-and-forget dispatch with async bus callback (non-blocking)
SkillTool — load skillload_skillTwo-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)

ToolPurpose
categoriesOrganize entries into groups
save_memory / delete_memory / search_memoryLong-term memory with source-based access control
generate_quizZero-token quiz generation — no LLM call, questions built from entry data
save_scenarioCreate practice scenarios with NPC persona + task dependency graph
save_examAI-generated exams with detailed explanations
complete_task / update_taskTrack 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:

AgentToolsExecutionVisibility
Main Agentsearch, read, write, update, categories, sessions_spawn, memory ops, generate_quiz, load_skillForeground, streams to WebSocketUser talks directly
Scenario NPCcomplete_task, update_taskForeground, separate sessionUser interacts on scenario page
memory_extractorsave_memoryBackground, silentInvisible to user, auto-triggered after 5+ turns
memory_consolidatorsave_memory, delete_memory, search_memoryBackground, silentInvisible to user, auto-triggered every 24h
scenario_buildersave_scenarioBackground, notifies on completionUser receives "Scenario ready!" notification
exam_buildersave_examBackground, notifies on completionUser 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 description
  • exam_builder — generates AI-written exams with explanations

System-level (auto-triggered, invisible to user):

  • memory_extractor — analyzes conversation after 5+ turns, extracts learning patterns
  • memory_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:

BlockContentStabilityCache Impact
Block 1: Identity"You are HarnessLingo, a {lang} learning assistant."Stable across sessionHigh cache hit
Block 2: Tool GuideAssembled from each tool's USAGE_GUIDE stringVaries by agent typeSemi-stable
Block 3: Agent RulesBehavioral constraints + available subagents + skillsPer-sessionSemi-stable
Block 4: Memory Rulessave/search/delete instructions + staleness markersOptional (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 subagent
  • merged — 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=auto memories (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:

  1. The loop yields a confirm_request event with a human-readable summary
  2. The frontend shows an approval dialog
  3. The user clicks Allow or Deny
  4. The decision resolves an asyncio.Future in the agent loop
  5. 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 NormalizedUsage format
  • 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.usage event flows through this bus to reach all subscribers simultaneously
  • Includes recursion guards and crash-safe listener isolation

3. Frontend Token Badge

  • A useTokenUsage hook subscribes to usage WebSocket events and tracks per-session totals
  • A TokenBadge component 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:

FeatureDescriptionStatus
Multi-model supportSupport 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 systemVoice input (STT) + natural TTS output for scenario role-play. Practice pronunciation and listening comprehension, not just text-based conversation.📋 Planned
Web search & article crawlerSearch 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
Ver o original no GitHub

Bom para

Relacionados