Shikigami Bot

Shikigami Bot is a personal AI agent platform built on Telegram. It routes your messages to specialized AI agents — each with its own personality, tools, and skills — using semantic classification. Agents run as Claude Code CLI subprocesses, keeping tool access and trust boundaries explicit. The platform is designed for single-operator use: you control which Telegram users can interact with it, which agents exist, and what each agent can do.

Architecture

Telegram
   |
   v
+-------------+
| Transport   |  aiogram adapter — raw Telegram message -> domain model
+-------------+
   |
   v
+-------------+
| Guardrails  |  Fail-closed allowlist — deny by default
+-------------+
   |
   v
+-------------+
|    Relay    |  Claude Haiku — semantic classification, session routing
|   Router    |  Returns: agent, session, confidence
+-------------+
   |
   v
+-------------+
|   Session   |  SQLite (dev) / Postgres (prod) — create or resume
|    Store    |
+-------------+
   |
   v
+-------------+
| Claude CLI  |  Subprocess with env allowlist and tool restriction
|  (adapter)  |  --append-system-prompt (trusted) / -p (untrusted input)
+-------------+
   |
   v
+-------------+
|  Response   |  Extract intent tags [REMEMBER:], [GOAL:], etc.
|   Parser    |
+-------------+
   |
   v
Telegram

Key Features

• Semantic routing: Messages are classified by topic and routed to the right agent automatically. Session continuity is determined by topic similarity, not timeouts.
• Confidence-gated HITL: When routing confidence falls below the configured threshold, the user is asked to confirm via inline keyboard before the agent responds.
• Structured trust zones: Agent definitions are immutable at runtime. Skills are append-only. Only session state is mutable.
• Prompt separation: Agent system prompts are passed via --append-system-prompt; user input via -p. They are never concatenated.
• Environment allowlist: The Claude CLI subprocess receives only PATH, HOME, and ANTHROPIC_API_KEY — never the full parent environment.
• Per-agent tool restriction: Each agent declares its tools in agent.yml. The adapter enforces this via --allowedTools.
• Fail-closed defaults: Empty allowlist denies all users. Missing API key triggers safe fallback routing. Required config fails at startup.
• Observability: Optional Langfuse integration for tracing (self-hosted or cloud).

Prerequisites

• Python 3.14+
• uv for dependency management
• Claude CLI (claude) on PATH
• A Telegram bot token (from @BotFather)
• An Anthropic API key (for relay classification and agent invocations)

Quick Start

git clone https://github.com/your-org/shikigami-bot.git
cd shikigami-bot
cp .env.example .env
# Edit .env with your tokens and allowed user IDs
uv run python -m shikigami_bot

The bot starts polling Telegram immediately. Send it a message from an allowed user ID to verify.

Configuration

All configuration is read from environment variables (or a .env file in the project root). See .env.example for a template with all fields.

Important: If ALLOWED_USER_IDS is empty, all users are denied. There is no "allow all" fallback.

To find your Telegram user ID, send a message to @userinfobot.

Agent Configuration

Agents live under the agents/ directory. Each agent is a subdirectory containing agent.yml and prompt.md.

Directory Structure

agents/
  general/
    agent.yml         # Required — config: name, model, tools, skills
    prompt.md         # Required — full system prompt
  research/
    agent.yml
    prompt.md
    skills/           # Optional — skill definitions
      briefing.md
      research.md

agent.yml

The agent.yml file is the agent's configuration.

name: research
description: Market intelligence, competitor analysis, deep research
model: opus            # haiku | sonnet | opus
orchestrator: false
tools:
  - WebSearch
  - WebFetch
  - Read
skills:
  - briefing
  - research

Fields:

prompt.md

The system prompt for the agent. Injected as trusted content via --append-system-prompt. If it contains a # Soul or ## Personality heading, the content after that heading is extracted as the personality block.

Skills

Skills are markdown files under agents/<name>/skills/. Each skill provides additional context or capability description that is loaded into the relay routing table. Skill content format is free-form markdown.

Minimal Agent Example

The simplest possible agent:

agents/
  myagent/
    agent.yml
    prompt.md

agent.yml:

name: myagent
description: Handles calendar and scheduling tasks
model: sonnet
tools:
  - Read
  - Write
skills: []

prompt.md:

You are a scheduling assistant. Help the user manage their calendar.
Be concise. Confirm before making changes.

Security Model

Shikigami Bot operates across three trust zones. The immutable zone contains agent definitions and source code — these are frozen at runtime and require a redeploy to change. The append-only zone contains skills that can be installed once but not modified from within the running system. The mutable zone is session state in the database, which is fully runtime-managed.

The platform is fail-closed: an empty user allowlist denies everyone, a missing API key triggers safe fallback routing, and required configuration missing at startup raises an exception rather than silently degrading. User input and agent system prompts are structurally separated at the CLI level and never concatenated. When routing confidence is low, the user must confirm the routing decision via an inline keyboard before the agent is invoked.

License

MIT