Metadata-Version: 2.4
Name: allimbot
Version: 0.5.0
Summary: Durable event and notification bridge for projects and coding agents.
Author: allimbot maintainers
License-Expression: MIT
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: desktop
Requires-Dist: pystray<0.20,>=0.19.5; extra == "desktop"
Requires-Dist: Pillow>=12.0; extra == "desktop"
Dynamic: license-file

# 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

```powershell
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:

```powershell
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:

```powershell
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.

```powershell
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:

```powershell
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:

```powershell
$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:

```powershell
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

```text
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:

```powershell
allimbot bridge codex --smoke
```

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

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

## Project SDK

```python
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

```powershell
$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](docs/cli-reference.md)
- [Configuration](docs/configuration.md)
- [Job files](docs/jobs.md)
- [Dashboard and tray](docs/dashboard.md)
- [Troubleshooting](docs/troubleshooting.md)
- [Current project status (Korean)](docs/PROJECT_STATUS.ko.md)
- [Changelog](CHANGELOG.md)

## 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](docs/PRODUCT_UX_PLAN.md).

## License

Allimbot is distributed under the [MIT License](LICENSE), preserving the
license of the original Allimbot implementation.
