GoLogX

GoLogX

> Tamper-evident logging for Go. An append-only, hash-chained, optionally signed log/slog handler: if anyone edits, deletes, reorders, or forges a line, logx verify catches it. Plus the everyday slog niceties, colored output, JSON, rotation, fan-out, and a CLI. No third-party dependencies, the integrity code is built on the Go standard library alone.

[](https://github.com/AyoubTadlaoui/GoLogX/actions/workflows/ci.yml) [](https://codecov.io/gh/AyoubTadlaoui/GoLogX) [](https://github.com/AyoubTadlaoui/GoLogX/actions/workflows/release.yml) [](https://pkg.go.dev/github.com/AyoubTadlaoui/GoLogX/logx) [](https://goreportcard.com/report/github.com/AyoubTadlaoui/GoLogX) [](LICENSE) [](https://glama.ai/mcp/servers/AyoubTadlaoui/GoLogX)

An agent's actions recorded into a signed, hash-chained log, then a single forged byte caught at the exact entry. Also available as [GIF](docs/screenshots/verify.gif) or [MP4](docs/screenshots/verify.mp4). Theme: atlas-ragnarok.

---

Why

Most logs are advisory. If something goes wrong and someone with write access wants the record to say something else, nothing stops them. For an audit trail, the kind you keep for a security review, a compliance ask, or to know what an autonomous agent actually did, that is not good enough. You want a log where any change after the fact is detectable.

GoLogX gives you that as an ordinary slog.Handler:

• Every record becomes an entry in a hash chain. Each entry's SHA-256 covers the one before it, so editing, deleting, reordering, or injecting a line breaks the chain at that exact point.
• With an Ed25519 key the entries are also signed, so they cannot be re-forged into a clean-looking chain by anyone who does not hold the private key.
• You read a log back offline with logx verify, which tells you whether it is intact and, if not, the first entry that was touched.

And it is still a good everyday logger: pretty colored output for humans, JSON for machines, size-based rotation, fan-out to several sinks, and a CLI that pretty-prints JSON logs from any pipeline. Built on the standard library, with zero external dependencies.

A note on where this fits

I also build npmguard, a pre-install gate that decides whether an npm package is safe before an AI agent installs it. GoLogX is the complementary half: npmguard gates what an agent is allowed to install, GoLogX keeps a tamper-evident record of what it then did. They are two separate tools that cover complementary ends of the same problem, not wired together.

---

Install

As a library

go get github.com/AyoubTadlaoui/GoLogX@latest

As a CLI

# Homebrew (macOS + Linux)
brew install AyoubTadlaoui/tap/logx

# Scoop (Windows)
scoop bucket add atlas https://github.com/AyoubTadlaoui/scoop-bucket
scoop install logx

# Arch Linux (via AUR)
yay -S logx-bin     # or: paru -S logx-bin

# Nix / NixOS
nix run github:AyoubTadlaoui/GoLogX

# Universal install script (Linux + macOS, amd64 + arm64), verifies SHA256
curl -fsSL https://raw.githubusercontent.com/AyoubTadlaoui/GoLogX/main/install.sh | sh

# Docker
docker run --rm -i ghcr.io/ayoubtadlaoui/logx:latest &1 | logx
logx -level=warn -grep=timeout app.log
logx -f /var/log/app.json          # tail follow

# audit
logx keygen -out audit             # make a signing keypair
logx verify -pubkey audit.pub a.log   # check integrity + signatures
logx verify a.log                  # chain-only check, no key

| Command | Purpose | |---|---| | logx [flags] [file ...] | Pretty-print JSON slog logs (stdin or files) | | logx verify [-pubkey k] [-quiet] file ... | Check a hash-chained log. Exit 0 intact, 1 tampered, 2 unreadable | | logx keygen [-out audit] [-force] | Write an Ed25519 keypair (.key, .pub) |

Pretty-print flags (-level, -grep, -f, -no-color, -source, -time, -version) are unchanged; lines that are not JSON are passed through untouched.

---

MCP server for AI agents

logx-mcp is a Model Context Protocol server that lets an AI agent keep and check a tamper-evident audit log of what it does. It speaks JSON-RPC 2.0 over stdio, the transport that Claude Code, Cursor, and Codex launch a server with, and exposes three tools wired to the audit core. It is the same zero-dependency code as the rest of GoLogX: standard library plus the local audit package, no MCP SDK.

The idea is simple. An agent that takes actions on your behalf should leave a record you can trust later. append_audit_entry writes each step into a hash chain, optionally signed, and verify_audit_log proves afterward that nothing in that record was edited, deleted, or reordered.

| Tool | What it does | |---|---| | verify_audit_log | Verify a chain's integrity. Returns intact, or the index and detail of the first entry that was edited, deleted, reordered, or forged. Pass pubkey_path to also check Ed25519 signatures. | | append_audit_entry | Append one tamper-evident entry (message, optional level, attrs, privkey_path) to a log, creating it if needed and resuming the existing chain across calls. | | read_audit_log | Read entries back. The chain is verified first, so tampered data is never returned as trustworthy. Use limit for the most recent N. |

A failed operation (a tampered log, an unreadable file) comes back as a tool result with isError set, with the detail in the text. A malformed call (unknown tool, missing required argument) comes back as a JSON-RPC error. Diagnostics go to stderr; stdout carries nothing but protocol messages.

Setup

Install the binary from source (or grab it from a release):

go install github.com/AyoubTadlaoui/GoLogX/cmd/logx-mcp@latest

Claude Code (claude mcp add, or in ~/.claude.json / a project .mcp.json):

{
  "mcpServers": {
    "gologx": {
      "command": "logx-mcp"
    }
  }
}

Cursor (~/.cursor/mcp.json or .cursor/mcp.json in the project):

{
  "mcpServers": {
    "gologx": {
      "command": "logx-mcp"
    }
  }
}

Codex (~/.codex/config.toml):

[mcp_servers.gologx]
command = "logx-mcp"

Use an absolute path to the binary if it is not on the client's PATH. Once it is connected, the agent can call the three tools above. Sign the log by passing privkey_path to append_audit_entry (and the matching pubkey_path to verify_audit_log); make the keypair with logx keygen.

---

API surface

| Symbol | What it is | |---|---| | audit.NewHandler(w, opts) | A hash-chained, optionally signed slog.Handler | | audit.OpenFile(path, opts) | Same, resuming the chain already in a file | | audit.Verify(r, pub) / audit.VerifyFile(path, pub) | Walk a log and report the first broken entry | | audit.GenerateKey() and the …KeyPEM helpers | Make and load Ed25519 keys | | logx.New(opts) / logx.NewHandler(opts) | Build a logger / handler from Options | | logx.NewPrettyHandler, logx.NewMultiHandler, logx.RotatingWriter | Pretty handler, fan-out, rotation |

---

Performance

Microbenchmarks on darwin/arm64, single record with three attributes, output discarded:

BenchmarkPretty-8        597.8 ns/op    16 B/op    1 allocs/op
BenchmarkStdlibJSON-8    579.1 ns/op     0 B/op    0 allocs/op
BenchmarkMulti-8         829.7 ns/op    16 B/op    1 allocs/op

The pretty handler is on par with stdlib TextHandler / JSONHandler. The audit handler does one SHA-256 (and one Ed25519 sign, if enabled) per record; run make bench to measure it on your hardware.

---

Common tasks

make test        # go test ./...
make test-race   # go test -race ./...
make bench       # microbenchmarks
make check       # gofmt + vet + race tests

---

Contributing

PRs and issues welcome. The bar is in [CONTRIBUTING.md](CONTRIBUTING.md). Run make check and open the PR once it is clean.

License

MIT, see [LICENSE](LICENSE).

---

About the author

Ayoub Tadlaoui, Atlas Kaisar, a problem-solver from Morocco, building software since 2016.

> "High performance knows no part-time commitment."

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: AyoubTadlaoui
• Source: AyoubTadlaoui/GoLogX
• License: MIT
• Homepage: https://pkg.go.dev/github.com/AyoubTadlaoui/GoLogX/logx

Install and usage instructions live in the source repository linked above.