hanuscode 1.0.1

Agente de programación autónomo para la terminal — agnóstico de modelos IA

HANUS CODE

Autonomous Programming Agent for Terminal and Web
_{AI Model Agnostic • Multi-provider • Extensible • SDK Included}

---

Table of Contents

• Features
• Installation
• Quick Start
• Terminal Usage
• Web Interface
• Project System
• SDK for Custom Agents
• Supported Providers
• Profile System
• Commands
• Agent Tools
• Plugins
• Subagents
• Skills
• Memory System
• Configuration
• API Reference
• Project Structure
• Examples
• Roadmap
• License

---

Features

• Multi-provider — Claude, OpenAI, Gemini, Ollama, GLM Cloud
• Autonomous mode — Completes tasks from start to finish without intervention
• Web Interface — Complete web panel with real-time chat, project management
• Project system — Create and manage projects with independent directories
• Profile system — Switch between roles: developer, architect, deep, speed
• Subagents — Delegate complex tasks to specialized agents
• Persistent memory — Remembers information between sessions
• Real-time streaming — Watch progress while working
• Task system — Automatic work tracking
• Extensible plugins — Add custom functionality
• Complete SDK — Create your own agents by importing modules

---

Installation

From PyPI

pip install hanuscode

From Source

git clone https://github.com/hanuscode/hanuscode.git
cd hanuscode
pip install -e .

---

Quick Start

Terminal

cd my-project/
hanuscode

Hanus analyzes the current directory and is ready to work.

Web UI

hanuscode
> /webui start

Open http://localhost:8080 in your browser.

---

Terminal Usage

Interactive Mode

cd my-project/
hanuscode

Command Mode (Non-interactive)

# Execute a command and exit
hanuscode --cmd "Analyze the project and generate a README"
hanuscode -c "Create a POST /api/users endpoint with validation"

# Specify directory
hanuscode --path /path/to/project --cmd "Refactor the auth module"

# Combine with profile and model
hanuscode --profile architect --model ollama/llama3 -c "Design the API"
hanuscode --mode bypass -c "Run the tests"  # No confirmations

CLI Arguments

Argument	Description
--cmd, -c	Command to execute (exits after completion)
--path, -p	Working directory (default: current directory)
--profile	Profile to use: developer, architect, deep, speed
--model	Model: provider/model (e.g., ollama/llama3, claude/claude-sonnet-4-6)
--mode	Permission mode: default, plan, bypass
--version, -v	Show version

Change settings within session

> /model ollama llama3          # Change provider/model
> /profile architect            # Change to architect profile
> /mode bypass                   # Change permission mode

Typical workflow

> Analyze the project structure
> The agent reads files, explores directories...

> Create a POST /api/users endpoint with validation
> The agent creates files, writes code, runs tests...

> Commit the changes
> The agent uses git for commit and push...

Permission modes

• default — Asks for confirmation for risky actions
• plan — Only plans, doesn't execute
• bypass — Executes everything automatically

/mode bypass     # Maximum autonomy
/mode default    # Balanced
/mode plan       # Planning only

---

Web Interface

Start web server

hanuscode
> /webui start          # Port 8080 by default
> /webui start 3000     # Custom port
> /webui stop           # Stop server
> /webui status         # View status

Web UI Features

• Real-time chat — Watch agent progress while working
• Project management — Create and select projects
• Model selector — Switch between models live
• Profile selector — Change agent behavior
• Tool visualization — See each tool executed
• Statistics — Tokens, costs, turns
• Server logs — Real-time debug
• History — Export conversations

HTTP Endpoints

Endpoint	Description
GET /	Web HTML interface
WS /ws	WebSocket for real-time communication

WebSocket Messages

// Send message
{ "type": "message", "content": "Your message" }

// Receive response
{ "type": "message", "role": "assistant", "content": "..." }

// Response streaming
{ "type": "stream", "content": "Partial text..." }

// Tool started
{ "type": "tool_start", "name": "read_file", "description": "Reading file: config.py" }

// Tool finished
{ "type": "tool_end", "name": "read_file", "result": "...", "success": true }

// Project management
{ "type": "create_project", "name": "My Project", "path": "/optional/path" }
{ "type": "select_project", "path": "/path/to/project" }
{ "type": "get_projects" }

---

Project System

Concept

Projects allow working on different directories in isolation. Each project has:

• Independent working directory
• Own configuration
• Saved sessions
• Project memory

Terminal usage

> /project create my-app
> Creates project in ~/.hanus/projects/my-app

> /project open /path/to/my/project
> Opens existing project

> /project list
> Lists all projects

> /project current
> Shows active project

Web UI usage

• Project selector in sidebar
• "New" button to create project
• "Open" button to open existing directory
• Active project shown in real-time

Project structure

~/.hanus/projects/my-project/
├── project.json        # Project metadata
├── sessions/           # Saved sessions
├── memory/             # Project memory
└── notes/              # Agent notes

---

SDK for Custom Agents

You can create your own agent by importing HanusCode modules.

See docs/custom_agent.md for complete guide on creating custom agents.

Basic example

from hanus.config import HanusConfig
from hanus.query_engine import QueryEngine
from hanus.tools import ToolExecutor
from hanus.permissions import PermissionManager, PermissionMode
from hanus.session_manager import SessionManager
from hanus.connectors.registry import ConnectorRegistry
from pathlib import Path

# Configuration
config = HanusConfig.load()
config.provider = "ollama"
config.model_id = "llama3"

# Create connector
connector = ConnectorRegistry.get(config.provider, config.get_connector_config())

# Create tool executor
executor = ToolExecutor(
    root_dir=Path.cwd(),
    permission_manager=PermissionManager(mode=PermissionMode.AUTO)
)

# Create session
session = SessionManager()
session.new_session(str(Path.cwd()), config.provider, config.model_id)

# Create agent engine
engine = QueryEngine(
    connector=connector,
    tool_executor=executor,
    session_manager=session,
)

# Configure system prompt
engine.set_system_prompt("You are a programming assistant.")

# Send message
response = engine.send("Analyze the current project")
print(response.text)
print(f"Tokens: {response.input_tokens} in, {response.output_tokens} out")
print(f"Cost: ${response.cost_usd:.4f}")

---

Supported Providers

Provider	Free	Popular Models
Ollama	✅	llama3, mistral, codellama, qwen2.5, glm-5
GLM Cloud	✅	glm-4, glm-4-flash, glm-5
Anthropic	💰	claude-sonnet-4-6, claude-opus-4-7
OpenAI	💰	gpt-4o, o1, o3-mini
Google	💰	gemini-2.0-flash, gemini-2.5-pro

Change model in real-time

/model ollama llama3
/model claude claude-sonnet-4-6
/model glm glm-4

API Keys configuration

# Environment variables
export ANTHROPIC_API_KEY=sk-ant-...
export OPENAI_API_KEY=sk-...
export GEMINI_API_KEY=...
export GLM_API_KEY=...

# Or in config.yaml
provider: claude
api_key: sk-ant-...

---

Profile System

Profiles change agent behavior based on context.

Available profiles

Profile	Description	Typical use
developer	General development, refactoring, documentation	Daily coding
architect	System design, architecture planning	New projects
deep	Deep analysis, thorough investigation	Complex problems
speed	Fast responses, quick iterations	Rapid prototyping

Profile management

/profile list           # View available profiles
/profile architect       # Switch to architect profile
/profile developer      # Switch to developer profile
/profile show           # View current profile

Create custom profile

# ~/.hanus/profiles/my_profile.yaml
name: my_profile
display: My Profile
description: Custom profile for my project
system_prompt: |
  You are an expert in {domain}.
  Your main focus is {objective}.
  Use these conventions: {conventions}
tools:
  - read_file
  - write_file
  - exec_cmd
  - web_search

---

Commands

Session commands

Command	Description
/help	Show help
/clear	Reset conversation
/save	Save current session
/sessions	List saved sessions
/resume [id]	Resume previous session
q / exit / quit	Exit agent

Configuration commands

Command	Description
/model [prov] [model]	Change model
/profile [name]	Change profile
/mode default|plan|bypass	Change permission mode
/budget [amount]	Manage budget
/config	Show current configuration

Project commands

Command	Description
/project create [name]	Create new project
/project open [path]	Open existing project
/project list	List projects
/project current	Show active project

Memory commands

Command	Description
/memory save [name]	Save memory
/memory search [query]	Search memory
/memory list	List memories

Task commands

Command	Description
/tasks	View system tasks
/task done [id]	Mark task as completed

Plugin commands

Command	Description
/plugins list	List installed plugins
/plugins available	List available plugins in repository
/plugins install <name>	Install plugin from repository
/plugins uninstall <name>	Remove a plugin
/plugins update <name>	Update plugin to latest version
/plugins enable <name>	Enable a plugin
/plugins disable <name>	Disable a plugin
/plugins reload [name]	Reload plugin(s)

Remote control commands

Command	Description
/telegram start	Start Telegram bot
/telegram stop	Stop Telegram bot
/telegram status	Show bot status
/telegram config	Show setup instructions
/webui start [port]	Start web interface
/webui stop	Stop web interface
/webui status	Web server status

Special commands

Command	Description
/reload	Reload project context
/multiline	Enter multiline input mode
/stats	Show session statistics
/logs	View recent logs

---

Agent Tools

File tools

Tool	Description	Example
read_file	Read file	<read_file path="config.py"/>
write_file	Create/overwrite file	<write_file path="app.py">code</write_file>
edit_file	Edit existing file	<edit_file path="app.py" old="foo" new="bar"/>
append_to_file	Append to end	<append_to_file path="log.txt">entry</append_to_file>
glob_search	Search files by pattern	<glob_search pattern="**/*.py"/>
grep_search	Search text in files	<grep_search pattern="def.*:" path="src/"/>

Execution tools

Tool	Description	Example
exec_cmd	Execute shell command	<exec_cmd>npm test</exec_cmd>
bash	Execute in bash	<bash>git status</bash>

Git tools

Tool	Description
git_status	Repository status
git_diff	Differences
git_commit	Make commit
git_push	Push to remote

Web tools

Tool	Description	Example
web_fetch	Get web content	<web_fetch url="https://..."/>
web_search	Web search	<web_search query="python asyncio"/>

Management tools

Tool	Description
task_create	Create task
task_update	Update task
task_list	List tasks
task_get	Get task

Interaction tools

Tool	Description
ask_user	Ask user with options
notebook_edit	Edit Jupyter notebook cells

Advanced tools

Tool	Description
subagent	Execute specialized subagent
structured_output	Generate structured output

---

Plugins

Plugins extend HanusCode capabilities with specialized functionality.

See docs/plugins.md for complete plugin development guide.

Plugin Management

Command	Description
/plugins list	List installed plugins
/plugins available	List plugins available in repository
/plugins install <name>	Install plugin from repository
/plugins uninstall <name>	Remove a plugin
/plugins update <name>	Update plugin to latest version
/plugins enable <name>	Enable a plugin
/plugins disable <name>	Disable a plugin
/plugins reload [name]	Reload plugin(s)

Official Plugin Repository

Browse and install plugins from the official repository:

https://github.com/hanuscode/hanuscode-plugins

# List available plugins
> /plugins available

# Install a plugin
> /plugins install telegram

# Update a plugin
> /plugins update telegram

Included plugins

Plugin	Description	Usage
arena	CTF arena challenge management	/arena start
binsmasher	ELF/PE binary analysis and exploitation	/binsmasher analyze ./binary
burpsuite	Burp Suite integration	/burpsuite scan
chrome	Chrome browser integration	/chrome start
code_review	AI code review	/review src/
cortex	Semantic memory with knowledge graphs	/cortex remember ...
deps_check	Dependency analysis	/deps_check requirements.txt
git_ops	Advanced git operations	/git_ops branches
metasploit	Metasploit framework integration	/metasploit list
notes	Bidirectional note linking with graphs	/notes new "Title"
search_code	Search in files	/search_code "pattern"
searchsploit	Search exploits database	/searchsploit apache
strategist	Strategic planning	/strategist plan
telegram	Telegram bot for remote control	/telegram start
weblearn	Web learning and crawling	/weblearn start
webui	Web interface	/webui start

Remote Control Plugins

Plugin	Description
telegram	Control HanusCode from Telegram with real-time notifications
webui	Complete web interface with real-time chat and project management
chrome	Chrome extension integration for browser-based tasks

Telegram Plugin Setup

Control your HanusCode agent remotely via Telegram:

# 1. Create bot with @BotFather on Telegram
# 2. Set token
export HANUS_TELEGRAM_TOKEN="123456789:ABCdef..."

# 3. (Optional) Set authorized users
export HANUS_TELEGRAM_ADMIN_IDS="123456,789012"

# 4. Start the bot
> /telegram start

# 5. Find your bot on Telegram and send /start

Create custom plugin

# hanus/plugins/my_plugin.py
NAME = "my_plugin"
DESCRIPTION = "My custom plugin"
USAGE = "command [args]"
AGENT_DOC = """
Plugin that does X, Y, Z.

Commands:
- /my_plugin cmd1 — Description
- /my_plugin cmd2 — Description
"""

def run(args: str = "") -> str:
    """Execute the plugin."""
    # Your logic here
    return "Plugin result"

---

Subagents

Subagents allow delegating complex tasks to specialized agents.

Subagent types

Type	Specialization	Use
explore	Read-only, code exploration	Find files, understand structure
review	Code review, bugs, security	Audits, code review
plan	Planning and design	Architecture, system design
test	Writing and running tests	Automated testing
general	General purpose	Various tasks

Subagent usage

<subagent type="explore" task="Find all API endpoints"/>
<subagent type="review" task="Review auth.py for vulnerabilities"/>
<subagent type="plan" task="Design the payment system architecture"/>
<subagent type="test" task="Write tests for the users module"/>

---

Skills

Skills are extensible commands installable from URLs.

Included skills

Skill	Description
/analyze	Project structure analysis
/explain	Explain code in detail
/todo	Find TODOs, FIXMEs, HACKs
/review	Code review
/deploy	Deploy to server
/test	Run tests

Skill management

/skill list                        # List available
/skill install <url>              # Install from URL
/skill create <name> <desc>        # Create new
/skill remove <name>              # Remove

---

Memory System

The agent can save and retrieve information between sessions.

Memory types

Type	Description	Use
user	User preferences	"User prefers TypeScript"
feedback	Lessons learned	"Don't use X, caused problems"
project	Project information	"Project uses JWT for auth"
reference	Pointers to resources	"Bugs are in Linear project ING"

Memory usage

> Save in memory that the project uses FastAPI with PostgreSQL
> <memory_save name="stack" type="project">
  The project uses FastAPI with PostgreSQL.
  Database: postgresql://localhost:5432/myapp
  Migrations: Alembic
</memory_save>

> What database does the project use?
> <memory_search query="database"/>
> (Retrieves saved information)

---

Configuration

Configuration file

~/.hanus/config.yaml:

# Provider and model
provider: ollama
model_id: llama3

# Working directory
root_dir: /home/user/projects/myapp

# Permissions
permission_mode: default  # default, plan, bypass

# Budget
budget_usd: 10.0

# Sessions
auto_save_session: true
session_dir: ~/.hanus/sessions

# Context
context_max_files: 50
context_include_content: true
context_preview_chars: 500

# Specific connectors
ollama_url: http://localhost:11434
anthropic_api_key: ${ANTHROPIC_API_KEY}
openai_api_key: ${OPENAI_API_KEY}

# Logging
log_level: INFO
log_file: ~/.hanus/hanus.log

Environment variables

# Provider
export HANUS_PROVIDER=claude
export HANUS_MODEL=claude-sonnet-4-6

# API Keys
export ANTHROPIC_API_KEY=sk-ant-...
export OPENAI_API_KEY=sk-...
export GEMINI_API_KEY=...
export GLM_API_KEY=...

# Ollama
export OLLAMA_URL=http://localhost:11434

# Budget
export HANUS_BUDGET=10.0

# Permission mode
export HANUS_PERMISSION_MODE=bypass

---

API Reference

Configuration

from hanus.config import HanusConfig

# Load configuration
config = HanusConfig.load()

# Attributes
config.provider          # "ollama", "claude", "openai", etc.
config.model_id          # Model ID
config.root_dir          # Working directory
config.permission_mode   # "default", "plan", "bypass"
config.budget_usd        # Budget in dollars
config.ollama_url        # Ollama URL
config.context_max_files # Max files in context

# Methods
config.get_connector_config()  # Config for connector
config.load_system_prompt()     # Load system prompt
config.save()                   # Save configuration

QueryEngine

from hanus.query_engine import QueryEngine

engine = QueryEngine(
    connector=connector,           # AI connector
    tool_executor=executor,        # Tool executor
    session_manager=session,       # Session manager
    permission_manager=perms,      # Permission manager
    plugin_manager=plugins,        # Plugin manager (optional)
    stream_callback=on_token,      # Streaming callback (optional)
    tool_start_callback=on_start,  # Tool start callback (optional)
    tool_end_callback=on_end,      # Tool end callback (optional)
    budget_usd=10.0,               # Budget (optional)
)

# Methods
engine.set_system_prompt(prompt)  # Set system prompt
engine.inject_context(context)     # Inject project context
engine.send(message)               # Send message, return Response

# Response
response.text           # Response text
response.input_tokens   # Input tokens
response.output_tokens  # Output tokens
response.cost_usd       # Cost in dollars
response.stop_reason    # Stop reason

---

Project Structure

hanus/
├── __init__.py            # Package entry point
├── __main__.py            # Entry point for python -m hanus
├── agent_runner.py        # Main agent loop
├── query_engine.py        # Agent engine (QueryEngine)
├── tools.py               # Tools (ToolExecutor)
├── ui.py                  # Terminal interface
├── config.py              # Configuration management
├── permissions.py         # Permission system
├── session_manager.py     # Session manager
├── profiles.py            # Profile system
├── action_parser.py       # XML action parser
├── action_handlers.py      # Action handlers
├── logger.py              # Logging system
├── monitor.py             # Event monitor
├── terminal_prompt.py     # Interactive prompt
├── project_tools.py       # Project tools
├── skill_manager.py       # Skill manager
│
├── connectors/            # AI provider connectors
│   ├── __init__.py
│   ├── base.py           # Base class
│   ├── registry.py       # Connector registry
│   ├── ollama.py         # Ollama connector
│   ├── anthropic.py      # Anthropic connector
│   ├── openai.py         # OpenAI connector
│   ├── google.py         # Google connector
│   └── glm_cloud.py      # GLM Cloud connector
│
├── profiles_builtin/      # Built-in profiles
│   ├── developer/
│   ├── architect/
│   ├── deep/
│   └── speed/
│
├── plugins/               # Included plugins
│   ├── arena.py           # CTF arena
│   ├── binsmasher.py      # Binary analysis
│   ├── burpsuite.py       # Burp Suite integration
│   ├── chrome.py          # Chrome browser integration
│   ├── code_review.py     # AI code review
│   ├── cortex.py          # Semantic memory
│   ├── deps_check.py      # Dependency analysis
│   ├── git_ops.py         # Git operations
│   ├── metasploit.py      # Metasploit integration
│   ├── notes.py           # Note-taking with graphs
│   ├── search_code.py     # Code search
│   ├── searchsploit.py    # Exploits database
│   ├── strategist.py      # Strategic planning
│   ├── telegram.py        # Telegram bot
│   ├── weblearn.py        # Web learning
│   └── webui.py           # Web interface
│
├── analysis/              # Code analysis
│   ├── __init__.py
│   └── dependencies.py   # Dependency graph
│
├── memory/                # Memory system
│   ├── __init__.py
│   └── manager.py
│
├── subagent/              # Subagent system
│   ├── __init__.py
│   ├── manager.py
│   └── types.py
│
├── plan/                   # Planning mode
│   ├── __init__.py
│   └── planner.py
│
├── context/                # Context compression
│   ├── __init__.py
│   └── compressor.py
│
└── tasks/                  # Task system
    ├── __init__.py
    └── manager.py

---

Examples

General development

> Create a REST endpoint for user management with full CRUD
> The agent creates files, writes code, adds validations...

> Add unit tests for the authentication service
> The agent creates tests, runs them, fixes errors...

> Document the API with OpenAPI/Swagger
> The agent generates documentation, creates swagger files...

> Refactor the users module to use repository pattern
> The agent restructures code, maintains functionality...

Code audit

> /profile deep

> Find SQL injection vulnerabilities in the code
> The agent analyzes files, finds dangerous patterns...

> Find hardcoded secrets in the project
> The agent searches for API keys, passwords, tokens in code...

> Review dependencies for known vulnerabilities
> The agent uses /deps_check to analyze requirements.txt...

SDK development

#!/usr/bin/env python3
"""Automatic documentation agent."""
from hanus.config import HanusConfig
from hanus.query_engine import QueryEngine
from hanus.tools import ToolExecutor
from hanus.permissions import PermissionManager, PermissionMode
from hanus.session_manager import SessionManager
from hanus.connectors.registry import ConnectorRegistry
from pathlib import Path

class DocGenerator:
    def __init__(self, project_path: str):
        self.project_path = Path(project_path)
        self.config = HanusConfig.load()
        
        self.engine = QueryEngine(
            connector=ConnectorRegistry.get(
                self.config.provider,
                self.config.get_connector_config()
            ),
            tool_executor=ToolExecutor(
                self.project_path,
                PermissionManager(mode=PermissionMode.BYPASS)
            ),
            session_manager=SessionManager(),
        )
        
        self.engine.set_system_prompt("""
You are a documentation generator. Your job is:
1. Analyze source code
2. Generate clear and complete documentation
3. Create READMEs, docstrings, and guides

Supported formats: Markdown, reStructuredText, Google Style.
""")
    
    def generate_readme(self) -> str:
        return self.engine.send("""
Analyze the project and generate a complete README.md with:
- Project description
- Installation
- Usage
- API Reference
- Examples
- Contributing
""")
    
    def generate_api_docs(self) -> str:
        return self.engine.send("""
Generate API documentation for all endpoints.
Include: methods, parameters, responses, examples.
""")

if __name__ == "__main__":
    import sys
    project = sys.argv[1] if len(sys.argv) > 1 else "."
    gen = DocGenerator(project)
    readme = gen.generate_readme()
    print(readme)

---

Roadmap

• Multi-provider (Ollama, Claude, OpenAI, Gemini, etc.)
• Profile system
• Extensible plugins
• Plugin repository and installation system
• Subagents
• Persistent memory
• Web interface
• Project system
• SDK for custom agents
• Telegram bot integration
• Chrome browser integration
• Semantic memory (Cortex)
• Dependency graph analysis
• IDE integration (VS Code, JetBrains)
• Team collaboration mode
• Advanced web dashboard
• CI/CD integration
• Complete REST API
• Webhooks for events
• Discord bot integration

---

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/my-feature)
3. Commit your changes (git commit -am 'Add my feature')
4. Push to the branch (git push origin feature/my-feature)
5. Open a Pull Request

Contribution guidelines

• Follow existing code style
• Add tests for new features
• Document public APIs
• Update README if necessary

---

License

MIT License

Copyright (c) 2026 CiTriX

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

---

Hanus Code — Code smarter, not harder.