OI Agent
OI ("ultron" on Discord) is a standalone bot that watches configured Discord
channels or whole guilds, answers only when explicitly triggered, and runs a
read-only audit of local git clones through OpenCode.
OI owns Discord transport, allowlists, rate caps, and delivery; OpenCode owns
model, tools, and repository exploration. With external_inputs = "read-only"
it also does public web research in an isolated second run.
Quick start
Requires Python 3.11+, uv, and a supported
OpenCode release (opencode --version).
uv sync --dev
opencode auth login --standalone # provider credentials for OpenCode
oi init --model provider/model # interactive: token, personality, watches
oi run # foreground run
oi initwrites~/.config/oi/config.tomland stores the Discord token as the environment variable named bydiscord_token_env(defaultOI_DISCORD_TOKEN) in~/.config/oi/secrets.env, mode 0600. The token value never appears in the config file oroi config show.- Non-interactive:
oi init --install-opencode --model provider/modelalso installs OpenCode through a fixed package-manager command (npm install --global opencode-ai, brew, ormise use --global npm:opencode-ai) and verifiesopencode --version; declining installation aborts setup.oi init --environment-mode workstation|serverandoi init --install-daemon(dedicated unprivileged user plus hardened systemd system unit) cover server setups. - Other commands:
oi pause/oi resume(global posting switch),oi doctor(preflight: OpenCode binary, model id, repos, token, state),oi queue status|retry|purge,oi session list|forget,oi memory status.
systemd user service
This checkout runs as a user service: ~/.config/systemd/user/oi.service
executes oi run --config ~/.config/oi/config.toml with Restart=always
(RestartSec=10) and a drop-in oi.service.d/mise-trust.conf carrying the
mise environment:
systemctl --user daemon-reload
systemctl --user enable --now oi.service
systemctl --user restart oi.service
journalctl --user -u oi.service -f # follow logs
Minimal config
discord_token_env = "OI_DISCORD_TOKEN"
opencode_model = "provider/model" # the model you authenticated in OpenCode
[[watch]]
channel_id = 123456789012345678 # or: guild_id = ... for a whole server
repos = ["/srv/repos/backend"]
bot_user_id = 345678901234567890 # the bot's own Discord user id
post_hourly_cap = 3
Install with npm
On Linux or macOS, oi installs from npm without any Python setup:
npm install -g divyachakshu # needs Node >= 18; no npm dependencies, no install scripts
oi --help
The npm package is a thin wrapper around the Python distribution
divyachakshu. The first oi run:
- finds
uv(PATH,~/.local/bin,~/.cargo/bin) or installs it with the official installer (UV_NO_MODIFY_PATH=1; yourPATHis not modified); - installs
divyachakshu, pinned to exactly the npm package's version, withuv tool install --force --python 3.11into a private uv root (~/.local/share/divyachakshu/npmon Linux,~/Library/Application Support/divyachakshu/npmon macOS;XDG_DATA_HOMErespected), so it never collides with anoiyou installed yourself; - hands your arguments, stdio, exit code, and SIGINT/SIGTERM/SIGHUP to the
installed
oi.
Later runs reuse the install; it is refreshed only when the pinned version
changes. OI_NPM_PACKAGE_SPEC=<spec> overrides the pin (development hook;
scripts/npm-sandbox-smoke.sh uses it for a locally built wheel). Windows is
not supported — use WSL2.
macOS (launchd)
On macOS the daemon runs as a per-user LaunchAgent; Linux systemd behavior is
unchanged. oi daemon install (or oi init --install-daemon) writes
~/Library/LaunchAgents/ai.divyachakshu.<service_name>.plist (rendered with
plistlib; RunAtLoad + KeepAlive; program arguments are the real Python
oi binary with run --config <path>; the environment PATH includes the
OpenCode bin dir; stdout/stderr go to ~/Library/Logs/oi/<service_name>.log),
then loads it with launchctl bootstrap gui/<uid> and starts it. Status and
logs: oi daemon status (launchctl print gui/<uid>/<label>) and oi daemon logs (tail of the log file); oi daemon uninstall boots the agent out and
removes the plist. User mode only: the dedicated-daemon-user system mode
refuses on macOS with a clear message. Not yet tested on real Mac hardware.
Configuration reference
Edit with oi config set KEY VALUE, oi config watch-add ..., oi config watch-remove ID, oi config show. Writes are validated before an atomic
replacement. Defaults:
| Key | Default | Meaning |
|---|---|---|
discord_token_env |
OI_DISCORD_TOKEN |
Name of the env var holding the Discord token. |
db_path |
~/.local/state/oi/state.db |
SQLite state (queue, sessions, memory). |
personality |
teammate-style default | Persona text handed to the model. |
max_reply_chars |
2000 |
Reply length cap. |
reply_delivery |
chunked |
chunked or single_message (must fit Discord's 2000-char limit). |
opencode_binary |
opencode |
Binary name or path; version-checked in isolation per run. |
opencode_model |
openai/gpt-4o-mini |
Model id passed to OpenCode. |
opencode_steps |
30 (max 50) |
Step budget for answer runs; research adds one per fetched URL. |
opencode_timeout_seconds |
900 (max 86400) |
Wall-clock cap per OpenCode run. |
environment_mode |
workstation |
workstation or server; legacy auto fails with a migration error. |
write_mode |
read-only |
read-only, or docs-only to allow edit access for documentation paths. |
write_dirs |
[] |
Directories docs-only may write; none usable means it refuses to widen. |
max_session_turns |
30 |
Completed deliveries before a conversation session rotates. |
session_ttl_days |
7 |
Idle days before rotation; 0 disables idle rotation only. |
max_context_messages |
200 (max 1000) |
Bounded history window shown to the model. |
max_context_age_days |
30 (max 365) |
Age cutoff for that window. |
reminder_channel_id |
0 |
Channel that receives posted reminders (0 = off). |
external_inputs |
disabled |
disabled or read-only (public web research; see below). |
max_external_evidence_items |
8 (1–50) |
Cap on evidence items and research source links. |
max_attachments |
4 (0–16) |
Attachments accepted per message. |
max_attachment_bytes |
8388608 (max 33554432) |
Per-attachment byte cap. |
image_inputs |
off |
off, or on to pass images as real image files. |
watches |
[] |
[[watch]] entries: channel_id or guild_id, repos, bot_user_id, post_hourly_cap (default 3), ignored_channels, allowed_channels. |
Using the bot in Discord
A message is answered only when it explicitly addresses the bot: written
<@bot-id> mention markup, a start with oi:, the marker #oi, #audit,
or #bugreport, or the bot's name used as a direct call (Ultron, …,
hey ultron, …, ultron?). A reply to one of the bot's messages counts
too, unless it addresses someone else (other <@…> markup, or a direct
call to another member or bot). Everything else is ignored (log reason:
no explicit trigger). Replies are capped at max_reply_chars and
delivered chunked by default.
Conversation sessions are scoped to (conversation, repository) and rotate
automatically after max_session_turns completed deliveries or
session_ttl_days idle days.
Commands (the command must be the leading token; multi-line arguments are one command):
| Input | Effect |
|---|---|
!fresh / !new |
Starts a new session for this conversation; optionally after the bot mention. |
!search <topic> |
Forces public web research on <topic>. |
!news <topic> |
Same, framed as news lookup. |
!web <topic> |
Alias of !search. |
!fetch <url> / !url <url> |
Fetches and summarizes that public URL. |
| plain phrases | "search the web/internet", "search online", "google X", "look up X online", "find/research X online or on the internet/web" also force research; the whole message becomes the query. |
Research input also includes every public http(s) URL found in the request
and in recent channel history when the message refers to links or URLs.
What the refusal replies mean (the public part is never answered from repository memory):
- "Public internet retrieval is disabled on this bot" —
external_inputsisdisabled(the default); set it toread-onlyto enable. - "That looks like a public lookup, but it doesn't name a public topic or URL" — no usable subject; reply with a topic or URL.
- "I can't look that up: it refers to private conversation content" — the subject points at chat content ("the token above"); OI only fetches public sources.
- "I couldn't decide whether this needs web research (the classifier is
unavailable right now)" — see troubleshooting;
!search <topic>bypasses the classifier.
Merge-request audits: MR 188 or !188 (GitLab), PR 188 or
pull request 188 (GitHub), or a canonical merge-request URL triggers a
read-only review instead of the checkout audit; bare numbers are ordinary
text.
How web research works
When external_inputs = "read-only", each request goes through two OpenCode
runs:
- A tool-free classifier (the configured model) decides whether the
request needs public research, answering one strict JSON object
(
{"research": bool, "query": str}) with one retry. Forced inputs (commands, plain web phrases, link references) skip it;disabledmode never calls it. - An isolated research run in an empty temporary directory and a
disposable home may use only
websearchandwebfetch. It sees the question plus publichttp(s)URLs from the request and recent history — never the repository, channel text, or OI credentials. Private, loopback, andfile:URLs are dropped.
Limits: topic capped at 200 characters; step budget opencode_steps plus one
per fetched URL; timeout 180 seconds plus 60 seconds per URL; research
summary capped at 6000 characters; sources and evidence items bounded by
max_external_evidence_items and a 12,000-character evidence budget. The
answer session receives the summary as bounded untrusted evidence; any
outbound link not in the research source list or the user's own message is
replaced with [link removed] and embeds are suppressed.
Troubleshooting
- Bot never replies — the message did not explicitly address the bot.
Write
<@bot-id>markup, start withoi:, use#oi,#audit, or#bugreport, call the bot by name (Ultron, …), or reply to one of its messages (a reply addressed to someone else stays silent); the log line showsno explicit trigger. 403/ "Missing Access" in logs — the bot is not in the configured guild (or lacks channel access). OI treats HTTP 401/403/404 as permanent and does not retry: invite the bot and check its channel permissions.No usable OpenCode .../ binary errors — the firstopencodeonPATHis often a launcher shim (npx/mise, distro wrapper). OI version-checks every candidate in its isolated environment and fails naming each rejection. Install a supported release (npm install --global opencode-ai, brew, ormise use --global npm:opencode-ai).- Service can't find
oioropencode(mise) — mise shims refuse to run in untrusted directories: trust the checkout (mise trust) and keep theoi.service.d/mise-trust.confdrop-in carrying the mise environment into the user service (systemctl --user cat oi.serviceshows it). - "classifier is unavailable" reply — the decision model returned no
usable JSON verdict even after one retry, so the public part is left
unanswered rather than answered from memory. Retry, or force the lookup
with
!search <topic>. - Doctor warning
model <id> not verified against OpenCode's model list; provider credential present— OpenCode returned an empty model listing; a warning, not a failure; otherwiseoi doctormust end inall checks passed.
Releasing
A single v* tag publishes both packages from GitHub Actions (agents never
publish):
- Bump
versionin bothpyproject.tomlandnpm/package.json— they must match;bash scripts/check-release-versions.shenforces it (on a tag push it also requires tagvX.Y.Z== version). - Commit, tag
vX.Y.Z, and push the tag.release.ymlthen:- builds the wheel/sdist and publishes
divyachakshuto PyPI by trusted publishing (OIDC,environment: pypi, no API token), then - publishes the
divyachakshunpm wrapper with provenance (OIDC, noNPM_TOKEN).
- builds the wheel/sdist and publishes
One-time bootstrap (owner + maintainer, before the first tagged release):
register a PyPI pending trusted publisher for project divyachakshu
(repo umiddey/divyachakshu, workflow release.yml, environment pypi); create
the npm package by publishing divyachakshu 0.1.0 once by hand; then register
the npm Trusted Publisher for the same workflow. Every later tag publishes
from Actions.
Development
uv sync --dev
uv run pytest # known baseline: 48 failures from a git-push fixture,
# pre-existing and unrelated to documentation changes
uv run ruff check . # line length 120
uv run python -c "import oi_agent"
Metadata
Release files for divyachakshu 0.1.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| divyachakshu-0.1.1.tar.gz | 432.4 kB | With provenance | Details for divyachakshu-0.1.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| divyachakshu-0.1.1-py3-none-any.whl | Python 3 | none | any | Details for divyachakshu-0.1.1-py3-none-any.whl |
Total release size: 655.1 kB
Release files / divyachakshu-0.1.1.tar.gz
| Download URL | divyachakshu-0.1.1.tar.gz |
|---|---|
| Size | 432.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
a64dbb9e81c63680b61f4f03ecc5cf5d2de724beed353a8340c9b43a9f1d376c
|
|
BLAKE2b-256 checksum How to use checksums |
75dd57317c6af7d4ce2c3283b392acb8802068b579a471a7c6a6ebd83d3242b5
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 20, 2026.
Transparency logRelease files / divyachakshu-0.1.1-py3-none-any.whl
| Download URL | divyachakshu-0.1.1-py3-none-any.whl |
|---|---|
| Size | 222.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
3e34c29e163ddd652d32da326c25148cef8ac18fb0385febf58c7e9186613903
|
|
BLAKE2b-256 checksum How to use checksums |
da85f2902c99021296b684b66ed471c9a70336651b229daa517b1f96700f9277
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 20, 2026.
Transparency logSecurity for divyachakshu 0.1.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for divyachakshu-0.1.1.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 20, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.