convez.ai
AgenteAutomaçãoAvançado
HanLi-Chainsea

HAN-Agents

HanLi-Chainsea/han-agents

Orquestração neuromorfa de tarefas para agentes de código com memória persistente

Ver no GitHub
InicialPluginScore · de 0 a 100

Sistema multi-agente inspirado em neurociência que fornece camadas de orquestração de tarefas, memória persistente e mapa de código para assistentes de IA. Implementa um loop de dispatch automatizado com detecção de desvios, memória semântica e checkpoints para projetos complexos que ultrapassam conversas.

Instalação

$npx convez-ai HanLi-Chainsea/han-agents

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
10
Forks
3
Acompanhando
0
Saúde
28%
Último commit
há 4 meses
Versão
—
Issues abertas
0
Contribuidores
1

Casos de uso

  • Projetos multi-etapa que precisam manter contexto entre conversas
  • Sistemas que rastreiam desvios entre especificação de skills e código real
  • Workflows automatizados com execução, crítica e documentação sem intervenção manual

Veredito

HAN é uma solução sofisticada de orquestração para agentes Claude que resolve problemas reais de persistência, memória e coordenação em projetos longos. Exige Python 3.8+ e integração profunda, mas elimina boilerplate e previne regressões em fluxos complexos.

README

A tradução para o português deste README ainda está na fila.

English | 繁體中文

HAN-Agents

Hierarchical Approached Neuromorphic Agents — a brain-inspired multi-agent task system for AI coding assistants.

Python 3.8+ SQLite FTS5 License: MIT Platforms


Clone once. Start immediately. No configuration required.

HAN auto-creates its database, registers hooks, and installs grammars the first time you use it.


What Is HAN?

HAN is a task orchestration layer that sits inside your AI coding agent. It gives your agent persistent memory, a live code map, and a structured workflow — so complex, multi-step projects don't fall apart between conversations.

Three layers work together:

┌──────────────────────────────────────────────────────────────────┐
│                          HAN System                              │
├─────────────────┬─────────────────┬─────────────────┬───────────┤
│   Skill Layer   │   Code Graph    │     Memory      │   Tasks   │
│    (Intent)     │   (Reality)     │  (Experience)   │(Execution)│
├─────────────────┼─────────────────┼─────────────────┼───────────┤
│  SKILL.md       │  code_nodes     │ long_term_      │  tasks    │
│  flows/*.md     │  code_edges     │   memory        │ checkpts  │
│  domains/*      │  file_hashes    │ working_        │ agent_    │
│                 │                 │   memory        │   logs    │
└─────────────────┴─────────────────┴─────────────────┴───────────┘
  • Skill Layer — intent definitions that guide agent behavior
  • Code Graph — live AST snapshot of your codebase (8 languages)
  • Memory — semantic search over past lessons; resumable checkpoints
  • Tasks — Jira-like hierarchy (Epic → Story → Task → Bug) with automated dispatch

Why HAN?

ChallengeWhat HAN does
Long tasks lose context between conversationsMicro-Nap checkpoints save and restore mid-task state
Agents repeat the same mistakesSemantic memory surfaces relevant lessons before each run
Hard to know if code matches the designDrift detection compares Skill definitions against actual code
Complex workflows require manual hand-holdingAutomated dispatch loop runs Executor → Critic → Memory without intervention
Setting up a new project takes too much boilerplateensure_project() auto-detects languages, frameworks, and test tools

Features

  • Zero-Config Start — database and hooks auto-initialize on first use
  • Automated Dispatch Loop — get_next_dispatch() orchestrates Executor → Critic → Memory pipeline end-to-end
  • Recipe System — pre-built workflows (e.g. recipe_unit_tests()) that generate full task trees from a single call
  • Code Graph — Tree-sitter AST with regex fallback; call graph and method extraction across 8 languages
  • Drift Detection — compare Skill definitions against actual code implementation
  • Semantic Memory — FTS5 + embedding search with LLM reranking
  • Task Lifecycle — full hierarchy with create, execute, validate, and document phases
  • Harness Tracing & Evals — local trace/span storage plus deterministic trajectory scoring
  • Auto Tech Stack Detection — ensure_project() detects languages, frameworks, and test tools
  • Micro-Nap Checkpoints — save and resume long-running tasks across conversations

Installation

Step 1: Clone

Choose your platform and clone to its skills directory:

# Global (recommended)
git clone https://github.com/Stanley-1013/han-agents.git ~/.claude/skills/han-agents

# Project-level
git clone https://github.com/Stanley-1013/han-agents.git .claude/skills/han-agents

Windows (PowerShell): replace ~ with $env:USERPROFILE

# Global
git clone https://github.com/Stanley-1013/han-agents.git ~/.cursor/skills/han-agents

# Project-level
git clone https://github.com/Stanley-1013/han-agents.git .cursor/skills/han-agents

Enable Skills in Cline-based Cursor: Settings → Features → Enable Skills

Replace the target path with your platform's skills directory:

PlatformDirectory
Windsurf.windsurf/skills/han-agents
Cline~/.cline/skills/han-agents
Codex CLI~/.codex/skills/han-agents
Gemini CLI.gemini/skills/han-agents
Antigravity~/.antigravity/skills/han-agents

Uses the Powers system — search for "han-agents" in Kiro's Powers panel or install from the GitHub URL.

Step 2: Just Start

That's it. No install script, no config file. On first use, HAN automatically:

  • Creates the database (brain/brain.db)
  • Copies agent definitions to your platform's agents directory
  • Registers hooks (Claude Code only)
  • Installs Tree-sitter grammars on demand

Set HAN_NO_INSTALL=1 to disable auto-initialization (useful in CI or air-gapped environments).

cd <path-to-han-agents>
python scripts/install.py --skip-prompts
FlagDescription
--skip-promptsNon-interactive mode
--allRun all optional setup steps
--add-claude-mdAdd config to project's CLAUDE.md
--init-ssotInitialize project SSOT INDEX
--sync-graphSync Code Graph
--resetReset database

Pre-install Tree-sitter grammars (optional — auto-installed on first use):

pip install -r requirements-ast.txt

Verify Installation

python scripts/doctor.py
python cli/main.py eval

Quick Start

Import

import sys, os
from servers import HAN_BASE_DIR
sys.path.insert(0, HAN_BASE_DIR)

from servers.facade import sync, status, check_drift, get_next_dispatch
from servers.tasks import create_task, create_subtask, get_task_progress
from servers.recipes import recipe_unit_tests, run_recipe
from servers.memory import search_memory_semantic, store_memory
from servers.project import ensure_project
from servers.tracing import start_trace, finish_trace
from servers.evals import evaluate_trajectory, evaluate_trace, extract_agents_from_trace

Initialize a Project

result = ensure_project('my-project', '/path/to/project')
# result['tech_stack'] → {'primary_language': 'python', 'test_tool': 'pytest', ...}

Or via CLI:

python cli/main.py init my-project /path/to/project

Recipe + Dispatch Loop

One call to generate a full task tree, then a loop to run it:

# 1. Recipe auto-analyzes the project and builds the task tree
result = recipe_unit_tests('my-project', '/path/to/project')
trace_id = start_trace('unit_tests recipe', project='my-project')

# 2. Dispatch loop — repeat until all tasks are done
while True:
    inst = get_next_dispatch(result['epic_id'], 'my-project', '/path/to/project', trace_id=trace_id)
    if inst['action'] != 'dispatch':
        break
    # Claude Code: dispatch via Agent tool
    Agent(subagent_type=inst['subagent_type'], prompt=inst['prompt'])

trace = finish_trace(trace_id)

get_next_dispatch() handles the full lifecycle automatically:

  • Executor → Critic validation (idempotent, no duplicate critics)
  • Rejected tasks → retry with feedback context
  • All done → Memory agent stores lessons learned
  • Returns model_tier for platform-specific model selection
  • With trace_id, records redacted dispatch/status spans for replay and evals

Agents

AgentTypeModel TierRole
PFCpfcplannerPlanning and task decomposition
ExecutorexecutorworkerTask execution
CriticcriticworkerValidation and quality checks
MemorymemoryfastKnowledge storage and retrieval
ResearcherresearcherworkerInformation gathering
Drift Detectordrift-detectorfastSkill-Code drift detection

Model Tier maps to semantic capability levels: planner (strongest reasoning), worker (balanced), fast (low-cost). Each platform maps these tiers to its own models.


API Reference

Facade — Unified Entry Point

The main interface for most workflows:

from servers.facade import (
    sync,              # Sync Code Graph from source files
    status,            # Project status overview
    check_drift,       # Detect Skill vs Code divergence
    get_full_context,  # Retrieve all three-layer context
    finish_task,       # Complete task lifecycle
    get_next_dispatch, # Auto-dispatch next agent in pipeline
)

Recipes

Pre-built workflows that generate full task trees:

from servers.recipes import (
    recipe_unit_tests, # Auto-generate unit test task tree
    run_recipe,        # Run recipe by name
)

Tasks

Full Jira-like task hierarchy management:

from servers.tasks import (
    create_task,           # Create task (epic / story / task / bug)
    create_subtask,        # Create child task (auto-inherits hierarchy)
    reserve_critic_task,   # Atomic critic reservation (idempotent)
    get_task_progress,     # Completion statistics
    get_epic_tasks,        # Epics with nested stories
    get_story_tasks,       # Tasks under a story
    get_hierarchy_summary, # Count by level: {epics, stories, tasks, bugs}
)

Project

from servers.project import (
    ensure_project,    # Auto-init: sync Code Graph + detect tech stack + store to DB
)

Code Graph

Live AST snapshot and traversal:

from servers.code_graph import (
    sync_from_directory,        # Sync a folder into the Code Graph
    get_class_dependencies_bfs, # BFS dependency traversal
    get_file_structure,         # Code structure of a single file
)

Memory

Persistent knowledge across conversations:

from servers.memory import (
    search_memory_semantic,  # Semantic search with LLM reranking
    store_memory,            # Store to long-term memory
    save_checkpoint,         # Create a Micro-Nap checkpoint
    load_checkpoint,         # Resume from checkpoint
)

Code Graph: Supported Languages

Tree-sitter provides full AST accuracy. A regex fallback is available for the languages marked below — HAN installs grammars automatically on first use.

LanguageExtensionsBackendCall GraphMethods
TypeScript.ts, .tsxTree-sitter (regex fallback)YesYes
JavaScript.js, .jsxTree-sitter (regex fallback)YesYes
Python.pyTree-sitter (regex fallback)YesYes
Java.javaTree-sitter (regex fallback)YesYes
Rust.rsTree-sitter (regex fallback)YesYes
Go.goTree-sitter onlyYesYes
C.c, .hTree-sitter onlyYes—
C++.cpp, .cc, .cxx, .hpp, .hh, .hxxTree-sitter onlyYesYes

To pre-install all grammars at once:

pip install tree-sitter tree-sitter-python tree-sitter-javascript tree-sitter-typescript tree-sitter-java tree-sitter-rust tree-sitter-go tree-sitter-c tree-sitter-cpp

CLI Reference

python cli/main.py <command>
CommandDescription
doctorDiagnose system status
initInitialize a project for HAN
syncSync Code Graph from source files
statusShow project status overview
driftCheck SSOT vs Code drift
graphQuery and explore the SSOT Graph
dashboardShow full system dashboard
ssot-syncSync SSOT Index to Graph
install-hooksInstall Git hooks for auto-sync
evalRun deterministic harness trajectory evals
tracesInspect local traces and guardrail events
reviewsInspect and resolve human review queue items
migrateApply numbered schema migrations
guardCheck guardrail policy for commands and paths

Examples:

python cli/main.py guard --agent executor --command "rm -rf /tmp/project"
python cli/main.py guard --agent executor --mode warn --command "rm -rf /tmp/project"
python cli/main.py eval --trace trace_abc --expected executor,critic,memory
python cli/main.py traces --export-jsonl /tmp/han-traces.jsonl
python cli/main.py traces --export-otel-jsonl /tmp/han-otel.jsonl
python cli/main.py reviews
python cli/main.py migrate --history

Utility Scripts

cd <path-to-han-agents>

python scripts/install.py --skip-prompts           # Install / update
python scripts/doctor.py                           # Verify installation
python scripts/sync.py /path/to/project            # Sync Code Graph
python scripts/init_project.py my-project /path/  # Init a project

Platform Compatibility

Supported Platforms

PlatformSkills DirectoryScope
Claude Code~/.claude/skills/ or .claude/skills/Global / Project
Cursor~/.cursor/skills/ or .cursor/skills/Global / Project
Windsurf.windsurf/skills/Project
Cline~/.cline/skills/ or .cline/skills/Global / Project
Codex CLI~/.codex/skills/ or .codex/skills/Global / Project
Gemini CLI.gemini/skills/Project
Antigravity~/.antigravity/skills/ or .antigravity/skills/Global / Project
KiroPowers system (one-click install)—

Feature Support

FeatureClaude CodeOther Platforms
Memory & Semantic SearchFullFull
Code Graph & Drift DetectionFullFull
Task Lifecycle ManagementFullFull
Multi-Agent CoordinationNative (parallel)Sequential

Claude Code's Agent tool enables parallel agent execution with isolated contexts. Other platforms run agents sequentially in a shared context.


Database

HAN uses SQLite at <han-agents>/brain/brain.db, auto-created on first use.

Requirements: Python 3.8+, SQLite 3.9+ (FTS5 required)


Documentation

DocumentDescription
SKILL.mdMain skill definition
reference/API_REFERENCE.mdComplete API documentation
reference/WORKFLOW_GUIDE.mdWorkflow patterns
reference/GRAPH_GUIDE.mdGraph operations
reference/TROUBLESHOOTING.mdCommon issues and fixes
docs/HARNESS_ROADMAP.mdTrace/eval/guardrail maturity roadmap
docs/QUICKSTART_HANDOVER.mdQuick start handover guide
docs/WHITEPAPER.mdArchitecture whitepaper

License

MIT

Ver o original no GitHub

Bom para

Relacionados