HelloAGI

An open-source governed autonomy runtime.
Not another chatbot wrapper. A practical agent runtime that can think, act, learn, and grow — with deterministic safety gates that prompt injection cannot bypass.

Install · Demo · Design · SRG · Tools · Architecture · API · Contribute

HelloAGI is an open-source autonomous agent runtime with deterministic governance. The agent plans and uses real tools to do real work, and every tool call runs through SRG — a Python policy engine, not a prompt — that cannot be jailbroken by the model it's governing. It runs local-first with the option of Telegram, Discord, local voice, and an HTTP API. It keeps per-principal memory and identity across sessions, and it's time-aware (current date, IANA timezone, UTC anchor in every turn).

What it looks like

you> clean up all .log files older than 30 days in /tmp

  🟡 bash_exec       ESCALATE  risk 0.62  →  awaiting your approval
                     find /tmp -name "*.log" -mtime +30 -delete
  [approve] [deny]

you> approve

  🟢 bash_exec       ALLOW     ran in 0.12s   (42 files removed)
  🟢 memory_store    ALLOW     saved skill "tmp-log-cleanup"

Cleaned 42 log files older than 30 days. I saved this as a skill, so next
time you can just say "clean logs" and I'll run the same workflow.

Three things are happening that most agents don't do:

1. SRG saw the bash_exec call, scored it, and blocked it for approval — the LLM couldn't talk its way past that.
2. Approval came back through the same Telegram / CLI session you were in — not a separate dashboard.
3. The successful workflow became a reusable skill the agent can invoke by name next time.

The 30-Second Start

curl -fsSL https://raw.githubusercontent.com/mmsk2007/helloagi/main/scripts/install.sh | bash

On Windows PowerShell:

irm https://raw.githubusercontent.com/mmsk2007/helloagi/main/scripts/install.ps1 | iex

That's it. The installer bootstraps HelloAGI, initializes the runtime, and launches the onboarding wizard immediately so users land in a ready-to-go session without fighting PATH issues. If pip fails inside Anaconda/Miniconda base (for example WinError 183 or broken ~package folders in site-packages), use a virtual environment instead — see Manual install below.

Docs by goal:

• Install and setup: docs/install.md
• CLI and commands: docs/cli-reference.md
• Migration: docs/migration.md
• Channels and extensions: docs/channels.md
• Security: docs/security.md
• Privacy: docs/privacy.md
• Environment variables: docs/environment.md
• Platforms: docs/platforms.md
• Troubleshooting: docs/troubleshooting.md
• Upgrade (feature flags, browser extra): docs/UPGRADE_GUIDE.md
• Vision: docs/HELLOAGI_VISION.md
• Implementation plan: docs/IMPLEMENTATION_PLAN.md

What Happens During Install + First Run

The installer launches a real setup flow immediately. The wizard now covers:

• environment detection and optional OpenClaw/Hermes import
• agent identity and focus
• runtime mode: cli, hybrid, or service
• active provider choice: template, anthropic, or google
• provider auth mode: api_key or auth_token
• Telegram, Discord, and local voice enablement
• local service auth token generation with HELLOAGI_API_KEY
• readiness checks and exact next commands

  ╦ ╦╔═╗╦  ╦  ╔═╗╔═╗╔═╗╦  v0.5.0
  ╠═╣║╣ ║  ║  ║ ║╠═╣║ ╦║
  ╩ ╩╚═╝╩═╝╩═╝╚═╝╩ ╩╚═╝╩

  Governed autonomy  ·  Evolving identity  ·  Local-first

  [#------] Step 1/7: Environment
    ok Python 3.9.18 on Windows
    ok Anthropic credential detected

  [##-----] Step 2/7: Agent Identity
    > Agent name: Lana
    > What should I call you: Alex
    > Your IANA timezone (e.g. America/New_York): America/New_York

  ...

  Setup complete (5/5 checks passed)

    $ helloagi run

Quick Commands

helloagi                                        # Interactive AGI session (auto-onboard on first run)
helloagi run                                    # Rich TUI with tool panels & governance indicators
helloagi oneshot --message "What can you do?"   # Single question
helloagi serve                                  # HTTP API on localhost:8787
helloagi serve --telegram                       # + Telegram bot
helloagi serve --discord                        # + Discord bot
helloagi serve --voice                          # + local wake-word voice channel
helloagi health                                 # Full local runtime + service health
helloagi service install --telegram             # Install local background service config
helloagi service start                          # Start local background service
helloagi service status                         # Inspect service + health
helloagi migrate --source openclaw              # Preview import from OpenClaw
helloagi migrate --source openclaw --apply --rename-imports
helloagi migrate --source hermes --apply        # Import Hermes secrets + artifacts
helloagi extensions list                        # Inspect optional extensions
helloagi extensions doctor                      # Check extension readiness
helloagi extensions enable telegram             # Persistently enable Telegram extension
helloagi runs list                              # Inspect orchestration runs
helloagi runs show <run-id>                     # Inspect a workflow run
helloagi onboard-status                         # Show saved + live runtime readiness
helloagi dashboard                              # Live monitoring dashboard
helloagi tools                                  # List all 23 built-in tools
helloagi skills                                 # List learned skills
helloagi update                                 # Upgrade in-place via pip
helloagi uninstall --yes                        # Remove installed package

Manual install (use this if the one-liner or pip install -e fails)

Use a virtual environment so HelloAGI does not fight a broken or crowded conda base (common on Windows: WinError 183, missing .dist-info, or half-removed packages named like ~atplotlib).

Windows (PowerShell) — from a clone:

cd helloagi
py -3 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -U pip
pip install -e ".[rich,telegram]"

If activation is blocked by execution policy, run once: Set-ExecutionPolicy -Scope CurrentUser RemoteSigned.

macOS / Linux — from a clone:

cd helloagi
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -U pip
pip install -e ".[rich,telegram]"

PyPI (no clone): after activating any venv:

pip install "helloagi[rich,telegram]"

Run the CLI without relying on PATH: the agi_runtime package must be installed in the active interpreter first, then:

python -m agi_runtime.cli onboard
python -m agi_runtime.cli run

Editable install needs a path: use pip install -e . (note the .), not pip install -e alone.

Unix install script (from a local clone):

git clone https://github.com/mmsk2007/helloagi.git
cd helloagi
./scripts/install.sh --source local

From onboarding to Telegram (step by step)

1. Activate the same venv you used for pip install (see above).

2. Install extras if you have not already: pip install "helloagi[rich,telegram]" or pip install -e ".[rich,telegram]" so python-telegram-bot is present.

3. Create a bot in Telegram: talk to @BotFather, choose New Bot, copy the HTTP API token.

4. Onboard from the directory where you want config files (helloagi.json, .env, helloagi.onboard.json, memory/):

   helloagi onboard
   

   The wizard can import an existing OpenClaw/Hermes setup, choose the active provider (template, anthropic, or google), accept api_key or auth_token auth modes, create the active auth profile, generate HELLOAGI_API_KEY for the local service, and enable Telegram, Discord, or local voice in the same flow.

   For scripted installs, the same setup can run without prompts:

   helloagi onboard --non-interactive --provider anthropic --auth-mode auth_token --runtime-mode service --enable-extension telegram
   

   Paste the Telegram token when asked (or add TELEGRAM_BOT_TOKEN=... to .env later). For model-backed replies, choose Anthropic or Google during onboarding and provide either the API key or auth token for that provider.

5. Initialize config if you skipped it: helloagi init (wizard may already create helloagi.json).

6. Start the API + bot (process stays in the foreground; keep this terminal open):

   helloagi serve --telegram
   

   Defaults: HTTP API at http://127.0.0.1:8787, Telegram long-polling in the same process.

7. In Telegram, open your bot, send /start, then send a normal message.

   By default, Telegram replies hide allow governance headers for a more natural chat flow
   (escalate/deny still show). Set HELLOAGI_TELEGRAM_SHOW_GOV=1 to always show headers.
   Multi-user memory/history is scoped per principal; set HELLOAGI_MEMORY_SCOPE=strict to
   disable legacy unscoped memory fallback.

   Reminder commands:

   • /remind in 30m | check deployment
   • /remind tomorrow 9am | standup prep
   • /remind cron:0 9 * * * | daily planning
   • /reminders
   • /reminder_cancel <id> / /reminder_pause <id> / /reminder_resume <id> / /reminder_run_now <id>

Optional background process: after helloagi service install --telegram, run helloagi service start. HelloAGI uses OS-native service backends where possible: Windows Scheduled Task, macOS launchd, Linux systemd --user.

Platform, Service, and Secret Model

• Secrets live in environment variables and local .env.
• Supported provider secret forms: *_API_KEY and *_AUTH_TOKEN.
• HELLOAGI_API_KEY is the shared auth token for the local API, dashboard, and service-aware clients.
• helloagi.onboard.json stores onboarding metadata only, not provider or channel secrets.
• helloagi auth list|show|activate|deactivate|doctor manages provider auth profiles and runtime precedence.
• Channels are optional extensions. Use helloagi extensions doctor to check readiness.
• helloagi serve and helloagi service install honor persistently enabled channel extensions.
• helloagi serve --require-auth enforces HELLOAGI_API_KEY even outside service mode.
• helloagi runs export <id> produces a redacted workflow summary for operator review.
• Migration imports secrets into .env, copies source artifacts into memory/imports/, and copies imported skills into memory/skills/.

How HelloAGI Is Different

Most agent stacks fall into one of two camps:

1. YOLO autonomy — AutoGPT-style loops that can execute anything the model emits. One hallucination can run rm -rf /.
2. Prompt-chain safety theater — LangChain/CrewAI-style orchestration where "safety" is a system prompt the model can talk itself out of.

HelloAGI is designed to be autonomous and governed at the same time. The things that actually make us different:

• SRG is code, not a prompt. Every tool call passes through a deterministic Python policy engine (governance/srg.py). The LLM has no way to bypass it because it never runs inside the LLM. See SRG: Deterministic Governance.
• Skill crystallization. A successful multi-step workflow can be saved as a reusable skill that the agent invokes by name later — not just chat history, real stored procedures.
• Persistent, per-principal identity and memory. Each Telegram/Discord/CLI principal has their own state, preferences, timezone, and relationship history. Conversations don't reset to zero.
• Grounded time awareness. Every system prompt includes current date, user-local clock, IANA timezone, and a UTC anchor, resolved per-principal. The agent knows what day it is and what zone you're in.
• ALE (Anticipatory Latency Engine). A content-addressed cache of the agent's own outputs for recurring intents — identical queries return without burning another model call.
• Circuit breakers + supervisor. Tool failures trip breakers; repeated dangerous patterns pause the loop. The agent doesn't spin forever.
• Runs local-first. Config, memory, journal, and policy live on your machine. Providers are swappable (Anthropic, Google) — or stub-only for tire-kicking.

What we don't claim

• We're not faster or cheaper than a bare model call for single-shot Q&A. ALE helps only for recurring intents.
• We're not a replacement for a coding agent like Claude Code or Cursor inside an IDE. HelloAGI is a runtime you embed in your own channels (chat, API, service).
• Template-only mode (no provider key) is a setup-check and demo surface, not real autonomy.

The Architecture

┌──────────────────────────────────────────────────────────────────┐
│                        USER INTERFACES                           │
│  CLI (Rich TUI)  │  HTTP API (SSE)  │  Telegram  │  Discord     │
└────────┬─────────┴────────┬──────────┴─────┬──────┴──────┬───────┘
         └──────────────────┴────────┬───────┴─────────────┘
                                     │
┌────────────────────────────────────▼─────────────────────────────┐
│                     AGENT KERNEL                                  │
│                                                                   │
│  ┌─────────────┐  ┌──────────────┐  ┌─────────────────────────┐ │
│  │ IDENTITY     │  │ SRG GOVERNOR │  │ ALE CACHE               │ │
│  │ Who am I?    │  │ Is it safe?  │  │ Have I seen this?       │ │
│  │ (evolving)   │  │ (always on)  │  │ (anticipatory)          │ │
│  └──────┬──────┘  └──────┬───────┘  └───────────┬─────────────┘ │
│         │                │                       │               │
│  ┌──────▼────────────────▼───────────────────────▼─────────────┐ │
│  │              AGENTIC TOOL-CALLING LOOP                      │ │
│  │                                                              │ │
│  │  User goal → Plan → Execute tools → Verify → Respond        │ │
│  │       ↑                                          │           │ │
│  │       └──── Re-plan on failure ◄─────────────────┘           │ │
│  │                                                              │ │
│  │  Every tool call: SRG gate → Circuit breaker → Execute →    │ │
│  │                   Supervisor → Journal → ALE cache          │ │
│  └──────────────────────────┬───────────────────────────────────┘ │
│                              │                                    │
│  ┌──────────────────────────▼───────────────────────────────────┐ │
│  │                    23 REAL TOOLS                              │ │
│  │  SYSTEM       WEB          CODE         MEMORY    USER       │ │
│  │  bash_exec    web_search   python_exec  mem_store ask_user   │ │
│  │  file_read    web_fetch    code_analyze mem_recall notify     │ │
│  │  file_write                             skills    delegate   │ │
│  │  file_patch                             session              │ │
│  │  file_search                                                 │ │
│  └──────────────────────────────────────────────────────────────┘ │
│                                                                   │
│  ┌───────────────────────────────────────────────────────────────┐ │
│  │                 INTELLIGENCE LAYER                            │ │
│  │  Personality Engine    │ Skill Crystallization                │ │
│  │  Growth Tracker        │ Context Compression                  │ │
│  │  Model Router          │ Semantic Memory (Gemini Embed)       │ │
│  │  Time/Situation Aware  │ Identity Evolution                   │ │
│  └───────────────────────────────────────────────────────────────┘ │
│                                                                   │
│  ┌───────────────────────────────────────────────────────────────┐ │
│  │                 ROBUSTNESS                                    │ │
│  │  Circuit Breakers │ Supervisor │ SSRF Protection │ Journal   │ │
│  │  Auto-Recovery    │ Incidents  │ Command Screen  │ Dashboard │ │
│  └───────────────────────────────────────────────────────────────┘ │
└───────────────────────────────────────────────────────────────────┘

SRG: Deterministic Governance

SRG (Safety & Risk Governor) is a deterministic Python policy engine — not a prompt, not a guideline. It runs before every action and cannot be bypassed, because it doesn't live inside the model.

User says: "Delete all my files"
  → SRG evaluates input: risk = 0.12, decision = allow
  → Agent plans: use bash_exec with "rm -rf /"
  → SRG evaluates tool call: DANGEROUS COMMAND DETECTED
  → Decision: DENY
  → Agent responds: "I can't do that. Would you like me to help clean up specific temp files instead?"

Why This Matters

Every other framework relies on the model itself to decide what's safe. That's like asking the employee to write their own performance review. HelloAGI separates governance from intelligence:

• The LLM decides WHAT to do (intelligence)
• SRG decides IF it's allowed (governance)
• They cannot be merged or bypassed (deterministic safety)

Three Decisions

What SRG Screens

• Dangerous commands: rm -rf, dd, fork bombs, chmod 777, pipe-to-shell
• Data exfiltration: os.environ, curl http://, requests.post(), /etc/passwd
• Sensitive paths: System directories, credential files
• Network operations: Outbound connections from code execution
• SSRF attacks: Blocks localhost, private IPs, internal hostnames

6 Policy Packs

helloagi run                          # safe-default (balanced safety)
helloagi run --policy coder           # full coding capabilities
helloagi run --policy research        # web research optimized
helloagi run --policy creative        # creative writing mode
helloagi run --policy reviewer        # read-only analysis
helloagi run --policy aggressive      # maximum autonomy

Tools

23 built-in tools, all governed by SRG on every call. No mocks — every one executes a real operation.

System & files

Web

Memory & skills

Reminders

Human-in-the-loop

Identity, Memory, and Time

Grounded time awareness

Every system prompt includes a <time-context> block:

Current date: Sunday, 2026-04-19
Local time: 21:22 (+03:00, Asia/Riyadh)
UTC: 2026-04-19T18:22Z

Timezone resolution order: per-principal override → runtime setting → host-local. So "remind me tomorrow at 9am" means 9am your time, not UTC, not server-local. Set your zone during onboarding or via /start on Telegram.

First-run wizard on every channel

CLI and Telegram both onboard a new principal before doing anything else:

• CLI wizard: agent name, owner name, IANA timezone (validated against zoneinfo), focus, provider, runtime mode, channels, service auth — all persisted.
• Telegram /start (new user): "What should I call you?" → "What's your IANA timezone?" → welcome. Stored in the per-principal profile, reused forever after.

Human-in-the-loop SRG approvals

When SRG escalates a risky tool call on Telegram, the agent sends an inline keyboard and blocks the agentic loop until you press Approve or Deny. Timeout (default 5 min) counts as deny. No silent auto-approvals.

Persistent identity + growth

• IdentityEngine carries the agent's name, mission, and principles across restarts and lets them evolve.
• GrowthTracker counts sessions, tool calls, skills learned, and streak days — used to personalize prompts, not as gamification dressing.
• SkillManager stores successful workflows as named, invocable skills.

API & Channels

HTTP API (7 Endpoints)

helloagi serve --port 8787

SSE Streaming

Watch your agent think in real-time:

curl -N http://localhost:8787/chat/stream \
  -H 'content-type: application/json' \
  -d '{"message": "Build me a web scraper for news headlines"}'

event: start
data: {"message": "Build me a web scraper..."}

event: tool_start
data: {"tool": "python_exec", "decision": "allow"}

event: tool_end
data: {"tool": "python_exec", "ok": true, "output": "..."}

event: response
data: {"text": "Done! I've created...", "tool_calls": 3, "turns": 2}

Telegram, Discord, and Voice

export TELEGRAM_BOT_TOKEN=your-token
helloagi serve --telegram

export DISCORD_BOT_TOKEN=your-token
helloagi serve --discord

helloagi serve --voice

Then open `http://127.0.0.1:8787/voice/monitor` to see the built-in live voice indicator while the local voice channel is listening, thinking, or speaking.

Full agent capabilities on every channel — same SRG governance, same tools, same personality. The voice channel routes reasoning through the normal HelloAGI provider stack and can use either local audio I/O or Gemini audio I/O.

On Windows, the voice channel uses the built-in System.Speech APIs through PowerShell, so you do not need a PyAudio wheel. On macOS and Linux, the voice extra installs SpeechRecognition + pyttsx3, and your OS may still need a local microphone backend.
If a user installed base helloagi first and enables voice later, they can recover in-place with helloagi extensions install voice.

To force a specific Gemini model for agent reasoning, set HELLOAGI_GOOGLE_MODEL in .env, for example gemini-flash-latest or gemini-3.1-pro-preview.
To transcribe the microphone with Gemini Live, set HELLOAGI_VOICE_INPUT_PROVIDER=gemini_live.
If the Live preview is unavailable, the channel falls back to HELLOAGI_VOICE_GEMINI_INPUT_MODEL for one-shot Gemini audio transcription.
To synthesize spoken replies with Gemini instead of the local OS voice, set HELLOAGI_VOICE_OUTPUT_PROVIDER=gemini_tts and optionally tune HELLOAGI_VOICE_GEMINI_TTS_MODEL / HELLOAGI_VOICE_GEMINI_TTS_VOICE.
To add audible “working on it” feedback while the agent is thinking or using tools, set HELLOAGI_VOICE_WORK_SOUND=piano (or chime, pulse, off).
To personalize voice acknowledgements, set HELLOAGI_OWNER_NAME, and to shape delivery further, use HELLOAGI_VOICE_GEMINI_TTS_STYLE. Gemini TTS also supports inline audio tags like [warmly], [serious], and [whispers] inside the spoken transcript.
By default, local voice now shares the same principal as local CLI (local:default), so memory carries across local text and voice. Override with HELLOAGI_VOICE_PRINCIPAL_ID if you intentionally want a separate voice profile.

Telegram reminder scheduler settings:

• HELLOAGI_REMINDER_TICK_SECONDS (default 5)
• HELLOAGI_REMINDER_STUCK_SECONDS (default 600)
• HELLOAGI_REMINDER_ONESHOT_GRACE_SECONDS (default 300)
• HELLOAGI_REMINDER_TIMEZONE (default UTC)

CLI Experience

HelloAGI ships with a beautiful Rich TUI:

┌──── HelloAGI Runtime ────────────────────────────────┐
│ Agent:   Lana (builder-mentor)                        │
│ Tools:   23 available | SRG: active                   │
│ Zone:    Asia/Riyadh  | 2026-04-19  21:22             │
│ Session: day 3 | 12 tool calls this week              │
└───────────────────────────────────────────────────────┘

you> Build me a CLI todo app in Python

  🟢 ⚡ python_exec (allow) ✓ Created todo.py...
  🟢 ⚡ file_write (allow) ✓ Saved to ./todo_app.py
  🟢 ⚡ python_exec (allow) ✓ Tests passing

🟢 [allow:0.05] | 3 tool calls in 2 turns

Slash Commands

For Developers

Project Structure

src/agi_runtime/
├── core/             # Agent loop, personality, runtime
├── governance/       # SRG — deterministic safety gate
├── tools/            # 23 builtin tools with decorator registration
├── skills/           # Skill crystallization and management
├── memory/           # Identity evolution, embeddings, compressor
├── api/              # HTTP server with SSE streaming
├── channels/         # Telegram, Discord, and voice adapters
├── robustness/       # Circuit breakers, supervisor
├── diagnostics/      # Dashboard, scorecard, replay
├── models/           # Multi-model routing (speed/balanced/quality)
├── policies/         # 6 governance policy packs
├── planner/          # LLM-powered goal decomposition
├── executor/         # Retry logic, failure recovery
├── verifier/         # LLM-powered outcome verification
├── orchestration/    # TriLoop, DAG engine, event bus
├── onboarding/       # Beautiful setup wizard + quotes
├── kernel/           # Full subsystem bootstrap
├── latency/          # ALE anticipatory cache
└── observability/    # JSONL journal

Adding a Custom Tool

from agi_runtime.tools.registry import tool, ToolParam, ToolResult

@tool(
    name="my_tool",
    description="Does something amazing",
    toolset="custom",
    risk="low",
    parameters=[
        ToolParam("input", "string", "What to process"),
    ],
)
def my_tool(input: str) -> ToolResult:
    result = do_something(input)
    return ToolResult(ok=True, output=result)

Your tool is automatically discovered, registered, gets SRG governance, and appears in the Claude tool schemas. Zero configuration.

Running Tests

pip install helloagi[dev]
pytest tests/

Design principles

• Intelligence is open-source. Not locked behind corporate walls.
• Autonomy requires governance. Unbounded power needs deterministic safety — in code, not in a prompt.
• Agents should grow. Per-principal memory, identity, and learned skills that persist across sessions.
• Local-first. Your data, your machine, your agent. Providers are swappable.

Contributing

git clone https://github.com/mmsk2007/helloagi.git
cd helloagi
pip install -e ".[dev]"
pytest tests/

See CONTRIBUTING.md for guidelines. New tools, channel adapters, policy packs, and honest benchmarks are all welcome.

Author

Created by Eng. Mohammed Mazyad Alkhaldi (Saudi Arabia).

"Whatever the mind can conceive and believe, it can achieve." — Napoleon Hill

License

MIT.