Maajun

Error monitoring that files the bug report — and can write the fix.

Maajun watches your error sources, investigates each new error against your source code, and documents it on GitHub. In suggest mode it opens an issue containing the root-cause analysis and a proposed patch. In fix mode it applies the patch on a branch, runs your test suite against it, and opens a pull request with the result.

Nothing merges without your review, in either mode.

Contents — Requirements · Installation · Quick start · How it works · Chat · Modes · Errors that are not bugs · AI providers · Configuration · Commands · Cost control · Security model · Documentation

Requirements

• Python 3.11 or newer
• An API key for one of Ox Alpha (free), DeepSeek, OpenAI, or Anthropic — see AI providers
• Optional, to open issues and pull requests: GitHub access, set up with maajun login — the GitHub CLI, a token, or SSH keys

Runtime-error monitoring reads log files, journalctl, and docker logs on the local machine, so the daemon has to run on the server your app is deployed on. The GitHub Actions monitor works from anywhere with network access.

Installation

uv tool install maajun     # or: pipx install maajun

From source:

git clone https://github.com/Morvin-Ian/maajun && cd maajun && uv sync

Quick start

Investigate one issue

No monitoring setup required — describe the problem and let maajun read the code:

maajun setup                                    # pick a provider, store its key
maajun report "Checkout 500s when the cart is empty"

This clones the target repo, analyzes it, and files an issue with a root-cause report. Add -m fix to open a pull request with the fix applied, or --dry-run to print the analysis and its cost without touching GitHub.

Monitor continuously

maajun setup             # provider key, GitHub, deployment, GitHub Actions
maajun status            # what is watched, and what is not
maajun watch             # watch in the background; the terminal comes back
maajun watch --status    # what has it done?
maajun watch --stop      # stop it

maajun login sets up GitHub access on its own, if you would rather do that first — it offers the GitHub CLI (it runs the login for you), a token, or your SSH keys, and then works out where each repo's errors land.

setup asks for the provider and its key, then offers GitHub and the error sources in turn. For each repo it probes this machine for how the app is deployed — its folder, its port, and whether its errors land in a log file, a systemd unit's journal, or a container's stdout — and offers what it finds, so the runtime errors your users hit are watched without you typing a path from memory. It detects the repo from your origin remote, and re-runs safely: every prompt defaults to your current configuration.

However you deploy — bare gunicorn, systemd, docker, compose, nginx in a container or on the host — errors land in one of those three sinks, and maajun discover finds which:

maajun discover                     # print what it finds, change nothing
maajun discover -r you/app --save   # record it

It also reads the code to answer what the host cannot: the stack, the entrypoint, which files the logging config really writes, and where errors are swallowed instead of logged — a bare except: pass, a 500 handler that logs nothing, a log directory nothing creates. What maajun watches then comes from the code rather than from memory.

Every prompt also has a flag, so once a key is in the keyring the rest can be reconfigured unattended:

maajun setup --non-interactive --repo you/yourapp --logs /var/log/app/error.log

maajun setup --non-interactive --provider openai --repo you/yourapp \
  --logs /var/log/app/error.log

--non-interactive cannot store a new API key — there is nowhere to prompt — so run maajun setup interactively once per machine first.

Without a configured repo, maajun runs in local mode: errors are still detected and analyzed, but each report is written to <workdir>/reports/<fingerprint>.md instead of opening a pull request.

How it works

1. Detect — a monitor picks up a new error where that repo's errors land: a log file, a systemd unit's journal, a container's stdout, or a failed GitHub Actions run.
2. Deduplicate — each error is fingerprinted. The same error is never reported twice; repeat sightings bump a counter on the existing incident. One that goes quiet and comes back is reported again, as a regression.
3. Triage — an error that is a guard doing its job is passed over. A rejected login, input that failed validation, a rate limiter returning 429: the code did what it was built to do, and there is nothing to fix. See Errors that are not bugs.
4. Analyze — the agent reads the relevant source in a clone under daemon.workdir and produces a what happened / root cause / suggested fix report, including the commit that likely introduced the bug and how the app runs where it broke (folder, port, docker or systemd).
5. Report — an issue in suggest mode, or a branch, a test run, and a pull request in fix mode. Always one or the other, and never empty: a report that comes back blank is re-asked once, then abandoned as a failed incident rather than filed as an empty issue.

The issue, the pull request, and the commit are all titled from the report's own one-line finding — not from the log line that triggered the run. An exception surfaces in one place and the defect is regularly in another, so KeyError: 'discount' would send a reader to the file that raised rather than the file that has to change. Titling from the analysis keeps the name of a bug and the fix for it pointing at the same thing. --dry-run prints the title it would file, so a mismatch is visible before anything is published.

Each incident records its token count and cost, viewable with maajun incidents.

Example report

The shape of a filed issue, abridged:

[maajun] cart/totals.py assumes promotions.apply() always writes a discount

What happened — Checkout raised an unhandled KeyError for carts created before a promotion was attached. 41 requests hit it in 12 minutes; every one returned a 500 at the payment step.

Root cause — cart/totals.py:88 reads cart["discount"] directly. The key is only written by promotions.apply() (cart/promotions.py:23), which returns early when no promotion matches — so the key is absent rather than zero.

Likely cause commit — 4f1c9ab "only apply promotions when one matches", which added that early return.

Suggested fix

-    discount = cart["discount"]
+    discount = cart.get("discount", Decimal("0"))

Source: logfile:/var/log/shop/error.log · First seen: 2026-08-03T03:14:22Z · Fingerprint: 9f3c1ab77e02d418

In fix mode the same analysis arrives as a pull request: the applied diff, the report committed as docs/incidents/<fingerprint>.md, and your test suite's verdict at the top of the body.

✅ Tests pass — pytest -q

A failing suite (❌ Tests fail (exit 1)) still opens the PR — a fix that breaks the tests is exactly what a reviewer needs to see.

Errors that are not bugs

Plenty of logged errors are the software working. A validator refusing a malformed email, a 401 for a bad password, a rate limiter returning 429, a 404 for a row that was never there — every one is a guard doing exactly what it was built to do. Filing a GitHub issue for those buries the errors that are real, so maajun does not.

Two passes decide, and neither one deletes anything:

Signatures, before any AI call. An error named after its own intent — ValidationError, PermissionDenied, 403 Forbidden, RateLimitExceeded, CSRF, 429 Too Many Requests, 404 Not Found — is closed without being analyzed, so it costs nothing. Deliberately narrow: it can only recognise errors that announce what they refused.

The agent's verdict, after reading the code. Every report opens with defect or by design. That is what catches a guard specific to your application — a paywall, a quota, a feature flag — which no shipped pattern could know about. A by design verdict is not published: no issue, no PR, no commit. A report that does not say, or says it cannot tell, is filed as a defect. Silence never suppresses a report.

Both are visible and reversible:

maajun incidents --ignored     # what was passed over, and why

[monitor]
ignore_by_design = false                    # analyze everything, however obvious
ignore_patterns = ["PaywallError", "QuotaExceeded"]   # your own guards

ignore_patterns are regexes matched against the raw error, tried before the shipped signatures. A pattern that does not compile is logged and skipped rather than stopping the daemon.

A guard that fires on input that should have been accepted is a defect, and so is one whose refusal escapes as an unhandled 500 — the check was intended, crashing on it was not. The prompt says so explicitly, so "by design" is not an exit from a hard investigation.

Chat

maajun chat is a conversational front end to everything above. It knows every command — the list is read from the CLI itself, so it is never out of date — and it remembers every incident maajun has handled.

maajun chat

Ask it how to do something and it answers from the real --help. Ask it to do the thing and it runs the command, showing you the exact line first if it changes anything:

> watch acme/web as well, in fix mode, verified with pytest

▸ Run: maajun add-repo acme/web -m fix
  Run it? (y/N): y

Answers stream as they are written, and each command or file edit is shown as it runs. maajun chat -p "..." answers one question and exits, for a script or a keybinding.

Read-only commands run straight away. watch, reset, and sign-out are never run from chat — it hands you the command instead. And because every incident, pull request, and issue is already in the database, so is the history:

> what did that checkout KeyError turn out to be?
> which PRs have you opened against acme/api this month?

Past chat sessions are searchable too — by words in any order, over any date range — and chat spend is recorded (/cost) and capped by chat.max_usd_per_day, separately from the daemon's budget. See the command reference for the slash commands and the full permission model.

Modes

Switch with maajun config github.mode fix, or per run with -m/--mode on watch and report.

Fix mode may still conclude that no code change is warranted. When it does, you get an issue rather than a pull request whose only diff is the incident report — the issue says why.

AI providers

Four are supported and interchangeable. maajun setup offers them in this order — cheapest first — and defaults to the first:

Ox Alpha is free. It is a stealth model on OpenRouter — a 1M-token reasoning model whose operator has not been named — offered at no charge for the length of its preview. You still need an OpenRouter key, but nothing is billed against it. It is one model with no cheap/premium split, so thinking_mode does nothing there. When the preview ends it stops being free without warning: watch what maajun incidents reports, and switch providers if the cost stops reading zero.

Switch at any time — the key for each provider is stored separately, so moving back and forth costs nothing:

maajun config ai.provider openai
maajun config ai.model gpt-4o        # override the default model
maajun provider-list                 # which providers have a key stored

Ox Alpha, DeepSeek, and OpenAI all speak /chat/completions, so any compatible gateway, proxy, or self-hosted server works too — point ai.base_url at it, and ai.provider still selects the request dialect and model defaults. Anthropic runs on the Messages API through the official SDK instead, and gets an explicit cache breakpoint on every request: without one Anthropic caches nothing, and each tool round would re-read the whole prompt at full price.

Configuration

Settings live in ~/.config/maajun/config.toml; pass -c/--config PATH to any command to use another file. setup writes it for you, and maajun config edits it in place with validation and comment preservation:

maajun config                      # print the whole config (secrets masked)
maajun config github.mode          # print one value
maajun config github.mode fix      # set a value (every repo, if several)
maajun config github.mode fix -r team/api    # ...or just one of them

A minimal config:

[ai]
provider = "ox-alpha"         # or "deepseek", "openai", "anthropic"
# model = "gpt-4o-mini"       # provider default if omitted
# thinking_mode = true        # use the provider's reasoning model

# One [[github.repos]] entry per repository, added with `maajun add-repo`.
# Omit the section entirely for local mode.
[[github.repos]]
repo = "owner/name"
base_branch = "main"
mode = "suggest"
# test_command = "pytest -q"  # verifies a fix-mode edit; result goes in the PR

# Where and how it runs, and where its runtime errors land. Any mix of the
# three sinks; fill it in with `maajun discover --save`.
[github.repos.deployment]
path = "/srv/myapp"
port = 8000
runs = "docker compose"
log_files = ["/var/log/nginx/error.log"]
docker_containers = ["myapp-web-1"]
# journald_units = ["myapp.service"]

[monitor]
log_files = ["/var/log/myapp/error.log"]
poll_interval = 30
# github_actions_repos = ["owner/name"]

[daemon]
workdir = "~/.local/share/maajun"   # clones, incident DB, state
# max_usd_per_day = 5.0             # 0 = no cap

[chat]
# max_usd_per_day = 5.0             # `maajun chat`'s own budget; 0 = no cap

At least one error source — log files or GitHub Actions — must be configured; the daemon refuses to start with nothing to watch. See the monitoring guide for every key, detection tuning, and multi-repo setups.

Credentials are never stored in this file. Provider API keys are read only from the OS keyring, under the service name maajun — maajun setup puts them there. Environment variables are never consulted.

The GitHub token is read from that keyring, and failing that from your GitHub CLI session — a credential you already manage, which maajun borrows rather than copies. maajun login picks between them, and maajun status says which is in use, so there is no doubt about what the daemon will push with. Branches can go over SSH instead, keeping the token to the API.

Most servers have no keyring. maajun does not stop for that: credentials go in ~/.config/maajun/credentials.json, a file only your user can read (chmod 600), and setup says so before it asks for anything. To use a keyring instead, install a backend for the environment maajun lives in — setup prints the right command (pipx inject maajun keyrings.alt, or the uv/pip equivalent). maajun status names wherever the credentials it has are kept.

Commands

Run maajun <command> --help for the full flag list, or see the command reference.

Cost control

daemon.max_usd_per_day defaults to $5. Past that, maajun stops analyzing for the rest of the UTC day, warns once, and keeps polling — skipped errors are picked up later, not dropped.

maajun config daemon.max_usd_per_day 20   # raise the cap; 0 disables it
maajun config chat.max_usd_per_day 20     # the same, for `maajun chat`

maajun chat has its own $5 daily cap. Past it a new question is refused with the command to raise it; an answer already being written is never cut off part-way.

Every incident's exact token count and cost is recorded and shown by maajun incidents, and --dry-run prints what an analysis would have cost.

The cheapest thing you can do is run on Ox Alpha, which bills nothing at all. For the rest, costs are computed from published list prices, in USD per 1M tokens. Input is priced three ways: a prompt prefix the provider has seen before is re-served from its cache far more cheaply than a fresh one, and maajun counts each from the token counts the provider reports.

Anthropic is the one provider that charges to write the cache — 1.25x a fresh token — so that column is counted separately rather than assumed free.

The DeepSeek rows are its peak rates. Off-peak it charges half of them, and maajun applies that automatically from the clock: peak is 01:00–04:00 and 06:00–10:00 UTC on weekdays, and Saturday and Sunday in Beijing time (UTC+8, so from 16:00 UTC Friday) are off-peak all day. OpenAI has no such schedule and is never discounted.

Because an investigation resends a growing prompt on every tool round, most of its input tokens are cache hits — so the same run costs a fraction of what the cache-miss column suggests. maajun incidents and --dry-run report what was actually billed.

On either provider's default model a single analysis costs cents, not dollars — but measure your own workload with --dry-run rather than trusting an estimate. Rates change; verify them against DeepSeek, OpenAI, Anthropic, or OpenRouter before relying on the cap. A model with no entry is costed at the most expensive rate in the table above, with no cache discount and no off-peak discount, so the cap errs towards stopping early rather than overshooting. The same goes for a gateway that reports no cache hits: every input token is charged at the miss rate.

Security model

• No shell access. The agent has no bash tool in any mode; there is nothing to grant.

• Scoped reads and writes. Every file tool is confined to an explicit set of directories, enforced by the tool layer rather than asked for in a prompt. The daemon's agent sees only the clone it is analyzing; maajun chat sees the directory you launched it in, daemon.workdir, and the log files named in your config. suggest mode is read-only on top of that; fix mode may edit inside the clone, never your running application.

• Secrets are refused, not merely unrequested. .env files, SSH and TLS keys, .netrc, .git-credentials, anything under .git/, and maajun's own incident database cannot be opened by any tool, even when they sit inside an allowed directory. What a tool reads goes to your AI provider — and, from the daemon, into an issue or pull request.

• Verification you control. test_command comes from your config, not from the model, so a fix cannot redirect its own verification.

• Chat proposes, you approve. maajun chat runs read-only commands freely, but anything that writes config or opens a pull request shows the exact command line and waits for a yes — or for a reason not to, which is passed on as an instruction rather than a bare refusal. A file edit shows its diff and the absolute path, flagged when it falls outside the project directory and daemon.workdir. reset and sign-out it will not run at all. run_maajun_command reaches maajun's own subcommands and nothing else — it is not a shell.

• Token hygiene. The GitHub token is passed to git via GIT_ASKPASS; it never lands in a remote URL, .git/config, or the process list.

Documentation

• How it works — components, monitors, and the incident pipeline
• Monitoring guide — full config reference, error sources, cost tracking, running on a VPS
• Command reference — every CLI command and flag

Development

uv sync            # install dev dependencies (pytest, ruff)
uv run pytest      # run tests
uv run ruff check  # lint

License

MIT.