Metadata-Version: 2.4
Name: hanuscode
Version: 1.0.1
Summary: Agente de programación autónomo para la terminal — agnóstico de modelos IA
Author: CiTriX
Author-email: CiTriX <hanuscode@outlook.es>
License: MIT
Project-URL: Homepage, https://github.com/hanuscode/hanuscode
Project-URL: Documentation, https://github.com/hanuscode/hanuscode#readme
Project-URL: Repository, https://github.com/hanuscode/hanuscode
Project-URL: Issues, https://github.com/hanuscode/hanuscode/issues
Keywords: ai,agent,autonomous,coding,programming,llm,claude,openai,gemini,terminal,cli
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development
Classifier: Topic :: Software Development :: Code Generators
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: colorama>=0.4.6
Requires-Dist: requests>=2.28.0
Requires-Dist: pyyaml>=6.0
Provides-Extra: claude
Requires-Dist: anthropic>=0.25.0; extra == "claude"
Provides-Extra: openai
Requires-Dist: openai>=1.0.0; extra == "openai"
Provides-Extra: gemini
Requires-Dist: google-generativeai>=0.5.0; extra == "gemini"
Provides-Extra: all
Requires-Dist: anthropic>=0.25.0; extra == "all"
Requires-Dist: openai>=1.0.0; extra == "all"
Requires-Dist: google-generativeai>=0.5.0; extra == "all"
Requires-Dist: tiktoken>=0.5.0; extra == "all"
Dynamic: author
Dynamic: requires-python

<p align="center">
  <img src="https://img.shields.io/badge/version-1.0.0-blue.svg" alt="Version">
  <img src="https://img.shields.io/badge/python-3.9+-green.svg" alt="Python">
  <img src="https://img.shields.io/badge/license-MIT-orange.svg" alt="License">
</p>

<h1 align="center">HANUS CODE</h1>

<p align="center">
  <strong>Autonomous Programming Agent for Terminal and Web</strong><br>
  <sub>AI Model Agnostic • Multi-provider • Extensible • SDK Included</sub>
</p>

---

## Table of Contents

- [Features](#features)
- [Installation](#installation)
- [Quick Start](#quick-start)
- [Terminal Usage](#terminal-usage)
- [Web Interface](#web-interface)
- [Project System](#project-system)
- [SDK for Custom Agents](#sdk-for-custom-agents)
- [Supported Providers](#supported-providers)
- [Profile System](#profile-system)
- [Commands](#commands)
- [Agent Tools](#agent-tools)
- [Plugins](#plugins)
- [Subagents](#subagents)
- [Skills](#skills)
- [Memory System](#memory-system)
- [Configuration](#configuration)
- [API Reference](#api-reference)
- [Project Structure](#project-structure)
- [Examples](#examples)
- [Roadmap](#roadmap)
- [License](#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

```bash
pip install hanuscode
```

### From Source

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

---

## Quick Start

### Terminal

```bash
cd my-project/
hanuscode
```

Hanus analyzes the current directory and is ready to work.

### Web UI

```bash
hanuscode
> /webui start
```

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

---

## Terminal Usage

### Interactive Mode

```bash
cd my-project/
hanuscode
```

### Command Mode (Non-interactive)

```bash
# 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

```bash
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

```javascript
// 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](docs/custom_agent.md) for complete guide on creating custom agents.**

### Basic example

```python
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

```bash
# 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

```yaml
# ~/.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](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
```

```bash
# 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:

```bash
# 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

```python
# 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`:

```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

```bash
# 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

```python
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

```python
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

```python
#!/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

- [x] Multi-provider (Ollama, Claude, OpenAI, Gemini, etc.)
- [x] Profile system
- [x] Extensible plugins
- [x] Plugin repository and installation system
- [x] Subagents
- [x] Persistent memory
- [x] Web interface
- [x] Project system
- [x] SDK for custom agents
- [x] Telegram bot integration
- [x] Chrome browser integration
- [x] Semantic memory (Cortex)
- [x] Dependency graph analysis
- [ ] IDE integration (VS Code, JetBrains)
- [ ] Team collaboration mode
- [x] 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.

---

<p align="center">
  <strong>Hanus Code</strong> — Code smarter, not harder.
</p>
