Skip to content
Menu

Audit module

Turns what the bot can see in your account into a snapshot, findings and at most three recommendations, each backed by evidence.

On this page

What it is for

Turns what the bot can see in your account into a snapshot, findings and at most three recommendations, each backed by evidence.

  • You want a first health check of your bot setup.
  • You want to see what changed since the last check.
  • You have monitoring turned on and the snapshot routine runs.
  • You want to send feedback about a report to the monitoring service.

Ask your bot

You do not type commands. Ask in plain words and the bot runs the module for you.

You ask
Check how my bots are set up and tell me what needs attention.
What you get back
The bot writes a Grok Bot Page with what it found, at most three recommendations with the evidence behind each, and a list of what it could not see.

What the bot does with it

  • The bot gathers what its own tools can see about your bots, routines, connectors, tasks and Pages, and hands that to the module.
  • The module applies fixed rules, such as a failing routine or a connector that needs to be signed in again.
  • The bot writes the findings, the recommendations and a list of what it could not see into a Grok Bot Page for review.
  • The module builds the report and tracks whether it was reviewed and sent. It has no network access and never sends anything itself.
  • A report leaves only through the send report tool, after you approve that tool call.

What it stores

Snapshots, baselines, recommendations and the state of each report live in one SQLite file, audit/audit.sqlite, in the bot's Ambitious folder (/workspace/ambitious by default). It stores short evidence lines and never full conversation transcripts.

The module has no screens of its own. It reads JSON, writes JSON, and keeps its data under /workspace/ambitious on the bot's computer. It never sends data anywhere.

Command reference

For the technically curious. You will rarely type these yourself; the bot runs them. Every command answers with the same envelope: whether it worked, which module and command ran, the data, and a list of errors with a hint for each. Open an example to see the command and its output.

ExampleAsk for recommendations from a stored snapshot. Each one cites the evidence it rests on.

Command

echo '{"snapshotId":"01954f2a-9c00-7b3e-8d21-4f6a0c9e1b57"}' | ambitious-audit recommend --json

Output

{
  "ok": true,
  "schemaVersion": 1,
  "module": "audit",
  "command": "recommend",
  "data": {
    "recommendations": [
      {
        "id": "failing-routine",
        "title": "Fix the failing routine",
        "why": "A failing routine is not doing its job. Read the short error it recorded, fix the cause, or pause it on purpose.",
        "evidenceIds": ["ev-1"],
        "effort": "small"
      }
    ]
  },
  "errors": [],
  "meta": { "now": "2026-03-02T09:00:00.000Z", "seed": 7, "version": "0.1.0" }
}
ExampleRecord that a person reviewed the report. The module answers that the next step is to send it.

Command

echo '{"reportId":"01954f2a-a3e8-7c10-9a44-2d7b8e5f6c01","state":"reviewed","at":"2026-03-02T09:05:00.000Z"}' | ambitious-audit report mark --json

Output

{
  "ok": true,
  "schemaVersion": 1,
  "module": "audit",
  "command": "report mark",
  "data": {
    "report": {
      "reportId": "01954f2a-a3e8-7c10-9a44-2d7b8e5f6c01",
      "snapshotId": "01954f2a-9c00-7b3e-8d21-4f6a0c9e1b57",
      "state": "reviewed",
      "reviewRequired": true,
      "failures": 0,
      "payloadSha256": "7d1f0c5b9a3e4826b1d0f7a2c6e5948310fb2a7c9d8e6f4051b3a2c1d0e9f8a7",
      "updatedAt": "2026-03-02T09:05:00.000Z"
    },
    "next": { "kind": "send", "reportId": "01954f2a-a3e8-7c10-9a44-2d7b8e5f6c01", "attempt": 1 }
  },
  "errors": [],
  "meta": { "now": "2026-03-02T09:05:00.000Z", "seed": 7, "version": "0.1.0" }
}
Show every command
commandsLists every command the module offers.
selfcheckChecks the installed file and the database, applies pending database updates and lists any problems in plain words.
snapshotStores the account observations the bot collected and returns a snapshot identifier.
baseline setMarks a snapshot as the baseline that later snapshots are compared with.
diffLists what changed between the baseline and a snapshot.
findingsApplies the rules to a snapshot and lists what they found, with severity and evidence.
recommendReturns at most three recommendations, each citing evidence from the snapshot.
report buildBuilds the exact report for a snapshot and says what the bot should do with it next.
report markRecords that a report was reviewed, sent, confirmed or failed, and returns the next step.
feedback buildBuilds a feedback note for the monitoring service without touching the database.

Source and releases

The module is open source under the Apache license. Each release carries one bundled file and its checksums; the bot installs it for you.