Allimbot

Allimbot is a durable notification and interaction bridge for project jobs, Codex, and Claude Code. The Python package, import namespace, and command are all named allimbot.

The design is one product with small integrations, not a copy of the bot inside every repository:

• producers write Event v1 records to a local SQLite spool;
• a worker sends them to a local, self-hosted, or future managed control plane;
• the control plane stores history and routes through provider adapters;
• lifecycle hooks detect agent attention, compaction, completion, and failures;
• the local Codex app-server bridge translates scoped actions without exposing local agent credentials to the cloud.

Current implementation

• Event, Action, and project-integration JSON contracts
• sub-100 ms local enqueue target with a durable SQLite spool
• scope-authenticated HTTP API (project ingest, device action, admin) and an accessible, responsive localhost operations dashboard
• local write-only provider settings and an in-dashboard Korean/English setup guide, including per-provider saves, clear stored-value feedback, and Kakao authorization without returning stored credentials
• a messenger view for channel-specific conversations, delivery outcomes, optional Telegram/ntfy inbound polling, search, and direct composition
• shared SQLite job state and redacted run history with age/size retention
• conflict-safe local job creation/editing with full validation, source revisions, atomic replacement, and write-only existing commands
• cross-midnight quiet hours and a transactional cross-process delivery limit
• optional Windows-first system tray for status, dashboard access, and pause/resume-all controls
• ntfy, Telegram, Discord, KakaoTalk, Gmail/SMTP, GitHub, Slack, and Matrix delivery
• Codex and Claude lifecycle-hook normalization
• Codex app-server stdio handshake, event mapping, action translation, and authoritative rate-limit polling
• validated Codex plugin bundle and Claude Code settings example
• policy recipes for Agent Runtime, Autofolio, Manipulator Control Tutorial, Linear Algebra for Robotics, Bean Wiki, and Ralph Automation
• fail-open command wrappers: a notification outage does not change the host command's result unless --strict-delivery is requested

Managed login, a hosted account UI, and KMS-backed provider credential storage are intentionally not simulated by the local prototype. They require the deployment choices listed in docs/DECISIONS_PENDING.md.

Install for development

python -m venv .venv
.venv\Scripts\Activate.ps1
python -m pip install -e .

A normal user installs a built wheel and the optional agent plugin; they do not clone this repository. See docs/INSTALLATION_MODEL.md.

First notification

Create a minimal provider template, enter credentials locally, and verify the configuration without printing any secret values:

allimbot init --channels ntfy,discord,kakao
# Edit .env locally. Do not commit it.
allimbot auth kakao
allimbot auth kakao --complete
allimbot doctor --channels ntfy,discord,kakao
allimbot doctor --channels ntfy,discord,kakao --send-test

init does not replace an existing environment file unless --force is provided. doctor validates locally by default; --send-test performs the external delivery check. Kakao authorization prints no token; --complete prompts for the one-time authorization code with hidden input and saves the returned access and refresh tokens in the selected environment file.

Wrap a command or inspect a job file:

allimbot run --title "Frontend build" --channels telegram -- npm run build
allimbot schedule validate --file jobs.example.json
allimbot schedule list --file jobs.example.json
allimbot schedule run heartbeat --file jobs.example.json
allimbot schedule start --file jobs.example.json

Global options may appear before or after an Allimbot subcommand. Put wrapped command arguments after -- so they are never interpreted as Allimbot options.

allimbot doctor --format json
allimbot run --quiet --lang ko -- python script.py
allimbot --env-file C:\secure\allimbot.env doctor

Local quickstart

Start an unauthenticated loopback-only control plane and load scheduled jobs:

allimbot serve --bind 127.0.0.1 --port 8765 `
  --jobs-file jobs.example.json --retention-days 30 --retention-max-mb 50

In another terminal, configure the producer and queue an event:

$env:ALLIMBOT_ENDPOINT = "http://127.0.0.1:8765"
$env:ALLIMBOT_PROJECT = "demo"
allimbot emit --type run.completed --summary "Batch finished" --flush
allimbot flush --watch

Open http://127.0.0.1:8765/ for overview, messenger history and direct sends, jobs, run history, channel health, settings, setup instructions, and events. Each provider block saves independently to the selected --env-file on loopback only. Existing secrets are never loaded back into the browser; a masked placeholder confirms that the saved value remains active. With --jobs-file, the Jobs screen can safely create, edit, and delete definitions; stale browser revisions are rejected instead of overwriting an externally changed file. A non-loopback bind is refused unless ALLIMBOT_API_TOKEN and --behind-https-proxy are both set; the public producer endpoint must use HTTPS. The Dashboard MVP intentionally has no remote browser login flow.

On Windows, optionally add the tray after the local server is running:

python -m pip install "allimbot[desktop]"
allimbot tray --url http://127.0.0.1:8765

The tray exits independently from the server. Pause-all affects future scheduled runs and does not terminate a command that is already running.

For an authenticated self-hosted instance, inject three separate credential classes. ALLIMBOT_PROJECT_TOKENS_JSON maps project IDs to ingestion-only tokens, ALLIMBOT_DEVICE_TOKENS_JSON maps device IDs to action-only tokens, and ALLIMBOT_API_TOKEN is the administrative dashboard/action-creation credential. Producers use ALLIMBOT_PROJECT_TOKEN; local bridges use ALLIMBOT_DEVICE_TOKEN. Do not place the administrator token in a project or CI environment.

To deliver stored events through configured providers, set ALLIMBOT_CHANNELS and the provider-specific environment variables in .env.example, then start serve. Projects never receive those provider secrets.

Commands

allimbot init       create a channel-specific environment template
allimbot doctor     validate channel configuration and optional delivery
allimbot auth       authorize an OAuth-based provider without printing tokens
allimbot emit       queue a structured event without network I/O
allimbot flush      deliver the durable producer spool
allimbot serve      run the local/self-hosted API, dashboard, and delivery worker
allimbot tray       run the optional Windows-first local tray controller
allimbot hook       consume one Codex or Claude hook event from stdin
allimbot bridge     supervise the Codex app-server protocol
allimbot run        run a command and preserve its exit status
allimbot send       send a notification directly
allimbot test       send a provider test notification
allimbot schedule   validate, list, start, or run local scheduled commands

All commands support human or JSON output through --format. Common user errors return stable AL-* codes; add --debug only when a traceback is needed for diagnosis. Notification content and selected CLI status text support --lang en and --lang ko.

Set ALLIMBOT_QUIET_START/ALLIMBOT_QUIET_END and ALLIMBOT_MAX_PER_MINUTE to preserve the legacy delivery guardrails. An intentional manual send, test, run, or doctor --send-test can bypass them once with --force-delivery; scheduled/background delivery stays guarded.

Verify the installed Codex protocol boundary without starting a model turn:

allimbot bridge codex --smoke

Start a bridge-owned Codex session, or resume a known app-server thread:

allimbot bridge codex --project agent-runtime --prompt "Check the current release gates."
allimbot bridge codex --project agent-runtime --resume-thread <thread-id>

Project SDK

from allimbot.integrations import ProjectEmitter, ProjectIntegration

policy = ProjectIntegration.load(".allimbot.json")
events = ProjectEmitter(policy)
events.emit(
    "experiment.completed",
    "Lab run finished",
    data={"lab": "lab04", "run_id": "run-42", "artifact_count": 3},
    dedupe_key="run-42-completed",
)

Unknown event types or metadata fields are rejected by the project policy. Autofolio's bundled policy marks financial-domain events sensitive and applies an explicit metadata allowlist.

Agent interaction

The Codex plugin in plugins/allimbot-codex observes session start, approval requests, compaction, and task completion. Deep Codex interaction uses the versioned app-server protocol over stdio.

For Claude Code, merge integrations/claude-code/settings.example.json into the appropriate settings file. Allimbot handles uniform notification/history; official Claude Remote Control or official Channels handles full conversation and permission relay. Hooks do not wait for a mobile reply.

Test and validate

$env:PYTHONPATH = "src"
python -m unittest discover -s tests -v
python -m compileall -q src

Plugin validation uses the Codex plugin-creator validator described in the development handoff. Security and architecture details are under docs/.

Operational references:

• CLI reference
• Configuration
• Job files
• Dashboard and tray
• Troubleshooting
• Current project status (Korean)
• Changelog

Legacy compatibility

The original send, test, run, and schedule commands remain available. run and scheduled jobs now fail open for notification errors by default. Add --strict-delivery only for channel probes where a delivery failure should be the command result.

Product and UX roadmap

The implementation sequence for CLI and notification UX, the local dashboard, and the Windows tray is tracked in the product UX plan.

License

Allimbot is distributed under the MIT License, preserving the license of the original Allimbot implementation.