~ $ man 7 agents

You debug it. Or AI does.

LogNorth gives agents the same context you'd read yourself.

Open the logs. Scroll. Search. Find the error. Context-switch to code. Trace it. Fix it. Deploy. Check if it worked.

an example session

$ agent "payments are failing in checkout"

[agent] Querying LogNorth for recent errors...
[agent] Found: Stripe::CardError in payment_service.rb:67 (23 hits, last 4m)
[agent] Stack: checkout_controller.rb:23 → payment_service.rb:67 → charge!
[agent] Reading codebase...
[agent] Root cause: live mode request with test card token
[agent] Writing fix...
[agent] Tests pass. Deploying.
[agent] Verified: 0 errors in last 5 minutes.

Done.

[01] why it works solo

Why this works if you're solo.

The bug is in 1 of 200 files. The stack trace is 14 frames deep. You need to cross-reference 3 log entries across 2 services. That is all context-loading, before you write a single fix.

Your codebase fits in a context window. The agent reads your errors, traces the call stack, greps your code, and writes the patch.

[02] what the agent reads

The same data you'd read, as a tool result.

No dashboard required. The issue, where it lives in your code, and which endpoints it hits.

tool · list_issues

{
  "issues": [{
    "error":       "Your card was declined.",
    "error_class": "Stripe::CardError",
    "error_file":  "app/services/payment_service.rb",
    "error_line":  67,
    "count":       23,
    "count_24h":   23,
    "first_seen":  "2026-03-29 14:28:00",
    "last_seen":   "2026-03-29 14:32:01",
    "paths":       ["/checkout"],
    "trend":       "up",
    "active":      true
  }]
}

The logs around it too, every line that led to it, in order.

logs · req-8f3a2b

14:32:01.003  POST /checkout                         12ms
14:32:01.015  Stripe::PaymentIntent.create           847ms
14:32:01.863  Stripe::CardError                      payment_service.rb:67

pattern: 23 occurrences in 4 minutes, all from /checkout
trend:   ↑ up

Steps, timing, patterns, repetitions. The agent sees the spike, reads the logs, and finds the root cause.

[03] connect

One command. Every agent connected.

Create an agent key in Settings > Developer. The same page shows this command with your URL and key in it. Run it in your terminal:

terminal

$ curl -fsSL https://lognorth.com/cli | sh -s -- https://logs.yoursite.com lgn-agent-...

✓ Connected to logs.yoursite.com: shop-prod, shop-staging
  Saved to ~/.config/lognorth/remote.json, readable by you only

Add LogNorth to Claude Code, Codex, Gemini CLI and Cursor? [Y/n]
  ✓ Claude Code  plugin lognorth
  ✓ Codex        plugin lognorth
  ✓ Gemini CLI   extension lognorth
  ✓ Cursor       ~/.cursor/mcp.json

It installs north, checks the key against your server, and adds LogNorth to every agent it finds. The key stays in one file on your machine, never in an agent's config. A cloud agent like Grok Bot sets itself up from the steps below.

[04] investigate → fix

From the alert to the fix.

Every alert email ends with /lognorth:investigate /checkout. Paste it. The agent walks the route a senior engineer would: what is wrong, when it started, the failing request, the code, and the commit that shipped just before.

/lognorth:investigate

> /lognorth:investigate /checkout

What is wrong  /checkout fails 18.2% of requests since 14:28. Normally 0.9%.
Since when     14:28, six minutes after commit 4e1b7c2 shipped.
The cause      Stripe::CardError at payment_service.rb:67, event 48213.
               4e1b7c2 sends a test card token in live mode.
The fix        Use the live token in payment_service.rb:67.
               Say the word and I'll make the change.

The fix is a proposal. The agent edits your code only when you say so.

the plugin's skills

/lognorth:investigate: an alert or an issue, to the cause and a proposed fix
lognorth: the investigation route. Loads when you debug production.
lognorth-integrate: adds the SDK to a Go, Node, or Rails app, then reads an event back to prove it works
/lognorth:connect: checks the connection, and says what to run when it is missing

[05] while you sleep

Alert at 3am. Fixed by breakfast.

LogNorth finds the problem. Your agent fixes it. Point the alert webhook at Grok Bot, or any agent that takes one. The agent reads the failing requests over MCP, writes the fix with a test, and opens a pull request. After the merge, it watches LogNorth until the errors stop. You wake up to a closed incident.

01 [lognorth] alert /checkout 8% vs 1%
02 [lognorth] webhook POST to the routine
03 grok bot investigate logs, trace, commits
04 grok bot fix branch + failing test
05 grok bot pull request #412 with the evidence
06 grok bot ship CI, merge, deploy
07 grok bot watch until /checkout is at 1%
08 grok bot fixed alert clears, report sent

LogNorth tells Grok Bot. Grok Bot does the rest. Neither one needs you.

Set it up with Grok Bot in three steps. The webhook docs.

[06] the tools

Eight tools. All read-only.

the agent gets eight tools

list_alerts: what is on fire, and since when
list_endpoints: which endpoints fail right now
endpoint_timeline: when it started
uptime_timeline: whether the app answers its ping, and why it did not
list_issues: what is broken
search_logs: the failing requests
get_event: one request, with its whole trace
list_apps: your apps

The agent can read events and issues, and there is no tool to change one. Your logs stay on your server: the agent asks your instance, and only the answer reaches your AI provider.

You get the same tools in your terminal: north tail follows the log and north top shows one app live. Terminal docs.

[07] for agents

Agent, set yourself up.

You are an AI agent with a terminal, and your user wants you to read their LogNorth. Follow these steps.

setup, for the agent

1. Ask your user for two values.
   Their LogNorth URL, for example https://logs.yoursite.com.
   An agent key from Settings > Developer in LogNorth. It starts with lgn-agent-.
   A key that starts with lgn- only is an app key. Ask for the agent key.

2. Connect over MCP, if you can add a remote MCP server or connector.
   URL     <url>/mcp
   Header  Authorization: Bearer <agent key>
   Transport: Streamable HTTP. Check it with the list_apps tool, then skip to step 5.

3. Otherwise, install north. No sudo. It checks the key before it saves.
   curl -fsSL https://lognorth.com/cli | sh -s -- <url> <agent key>
   The installer prints where north is, often ~/.local/bin/north. If that
   folder is not on your PATH, call north by that full path.
   ~/.local/bin/north call list_apps

4. With north, call the tools from the shell. Each one prints JSON.
   north call list_alerts
   north call list_endpoints '{"app_id": 2, "since": "1h"}'
   north call endpoint_timeline '{"path": "/checkout", "app_id": 2, "since": "6h"}'
   north call search_logs '{"errors_only": true, "since": "2h"}'
   north call get_event '{"id": 48213}'   # an id from search_logs
   Pass app_id, from list_apps, whenever there are several apps.
   Or add it as a stdio MCP server: command north, args ["mcp"].

5. Investigate in this order. list_alerts, then endpoint_timeline
   for when it started, search_logs for what failed, get_event for one
   full trace and error_file:error_line, then the commits just before.

6. If your user wants you to receive alerts, create a webhook your
   user can POST to, and give them its URL and key. They paste both in
   LogNorth under Settings > Alerts > Webhook. Each alert arrives as JSON:
   title, message, text, sent_at. The message ends with
   /lognorth:investigate <path or issue>: start there.

Rules. Never print the key. Every tool is read-only: you cannot mute,
   delete, or change anything in LogNorth. Say when a cause is a guess.
   If north says the key was rejected, ask your user for a new agent key.

In a cloud agent, the LogNorth server must be reachable from the internet. Give the agent its own key, so you can revoke it without touching yours. Every tool and argument.

Read the error. Trace the cause. Write the fix. Verify the deploy.

Four steps. Zero tabs.

Read the MCP docs → Open demo →