hanuscode 1.0.0__py3-none-any.whl

hanuscode-1.0.0.dist-info/METADATA

@@ -0,0 +1,1151 @@
+Metadata-Version: 2.4
+Name: hanuscode
+Version: 1.0.0
+Summary: Agente de programación autónomo para la terminal — agnóstico de modelos IA
+Author: CiTriX
+Author-email: CiTriX <citrix@example.com>
+License: MIT
+Project-URL: Homepage, https://github.com/citrix/hanuscode
+Project-URL: Documentation, https://github.com/citrix/hanuscode#readme
+Project-URL: Repository, https://github.com/citrix/hanuscode
+Project-URL: Issues, https://github.com/citrix/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>