self-escalate-agent

A minimal CLI agent that knows when it's stuck and asks for help — automatically.

When the agent cannot confidently complete a task, it opens a GitHub issue so a human can follow up. No silent failures.

Demo

Three scenarios in one session:

1. Normal conversation

You
› 你好！有什麼我可以幫助你的嗎？

Agent:
嗨！你好！😊 有什麼我可以幫助你的嗎？

2. Capability gap → auto-escalation

The agent recognises it cannot fetch real-time weather and immediately opens a GitHub issue instead of guessing or redirecting the user.

You
› 有啊，你知道今天天氣如何嗎

Agent:
很抱歉，我沒有辦法獲取您當前位置的即時天氣資訊。
This capability isn't available yet. The system will open an issue so the team can add it.

Escalated → https://github.com/your-org/your-repo/issues/42

3. Direct resolution

When the agent can answer from its context (e.g. reading SOUL.md), it resolves the session without escalating.

You
› 你可以幫我解釋一下你的 SOUL.md 嗎

Agent:
好的！以下是 SOUL.md 的內容解釋：...

resolved ✓

---

How it works

Every response the agent produces ends with a self-assessment:

{
  "converged": true,
  "confidence": 0.9,
  "reason": "Found a direct answer from a reliable source."
}

If converged is false and confidence is below 0.7, the session is automatically escalated: a GitHub issue is opened with the full conversation context so a human can pick it up.

Installation

Requires Python 3.11+ and uv.

git clone https://github.com/jason8745/self-escalate-agent
cd self-escalate-agent
uv sync

Configuration

Copy .env.example to .env and fill in the values:

cp .env.example .env

Variable	Required	Description
ANTHROPIC_API_KEY	Yes	Anthropic API key for Claude
GITHUB_TOKEN	Yes*	GitHub personal access token (needs repo scope)
GITHUB_REPO	Yes*	Target repo for escalation issues (owner/repo)
SELF_ESCALATE_HOME	No	Session storage path (default: ~/.self-escalate)

* Required only if you want escalation to work. Without these, the agent will warn on startup and fail when escalation is triggered.

The Makefile auto-exports variables from .env, so make run picks them up automatically. For other invocations, source the file first:

export $(grep -v '^#' .env | xargs)

You can also use the config set command to get the right export statement:

self-escalate config set escalation.github.token ghp_...
# Prints: export GITHUB_TOKEN="ghp_..."

Supported config keys: escalation.github.token, escalation.github.repo, escalation.provider.

Usage

Start a chat session

uv run self-escalate chat
# or
make run

Options:

Flag	Description
--domain NAME	Load a domain plugin (e.g. general)
--persist	Save resolved sessions to $SELF_ESCALATE_HOME/sessions/

Type /exit or /quit to end the session. Press Ctrl+C to exit.

Domain plugins

Domain plugins inject a custom system prompt and tools into the agent for a specific problem area.

# List installed plugins
self-escalate plugin list

# Install a plugin from a local directory
self-escalate plugin install ./my-plugin

# Use a plugin in a chat session
self-escalate chat --domain my-plugin

A plugin directory must contain a plugin.py with a class that extends DomainPlugin. See plugins/domain/general/ for a minimal example.

Development

make install   # install dependencies
make test      # run tests
make lint      # check style
make format    # auto-fix style
make clean     # remove __pycache__ and .pytest_cache

Architecture

cli.py                        # click CLI entry point
agent/
  core.py                     # TaskAgent — LLM loop + self-assessment extraction
  escalator.py                # delegates to an EscalationPlugin
  prompt_builder.py           # builds the system prompt
  session.py                  # Session and Attempt dataclasses
tools/                        # web_search, terminal, file_ops, memory (auto-registered)
plugins/
  domain/                     # domain plugins (general included)
  escalation/github/          # GitHub escalation plugin
memory/                       # flat MEMORY.md store

The escalation threshold (AUTO_RESOLVE_CONFIDENCE = 0.7) is defined in agent/session.py.