A Technical Deep-Dive for the Security-Conscious

Jeremy Brown — Wed, 13 Aug 2025 18:36:01 +0000

I've been using AI coding assistants like Copilot and Claude a lot, but I constantly hit the limits of their context windows, forcing me to re-explain my code over and over. I also work on projects with sensitive IP, so sending code to a third-party service is a non-starter.

To solve this, I built AntiGoldfishMode: a CLI tool that gives your AI assistant a persistent, local-only memory of your codebase.

It's built with a few core principles in mind:

Local-First & Air-Gapped: All data is stored on your machine. The tool is designed to work entirely offline, and you can prove it with the agm prove-offline command.
Traceable & Verifiable: Every action is logged, and all context exports can be cryptographically signed and checksummed, so you can verify the integrity of your data.
No Telemetry: The tool doesn't collect any usage data.
The core features are MIT-licensed and free to use. There are also some honor-system "Pro" features for advanced code analysis and stricter security controls, which are aimed at professional developers and teams.

You can check out the source code on GitHub: https://github.com/jahboukie/antigoldfish

The entire security posture is built on a zero-trust, local-first foundation. The tool assumes it's operating in a potentially untrusted environment and gives you the power to verify its behavior and lock down its capabilities.

Verifiable Zero-Egress We claim the tool is air-gapped, but you shouldn't have to take our word for it.

How it works: At startup, the CLI can monkey-patch Node.js's http and https modules. Any outbound request is intercepted. If the destination isn't on an explicit allowlist (e.g., localhost for a local vector server), the request is blocked, and the process exits with a non-zero status code.
How to verify: Run agm prove-offline. This command attempts to make a DNS lookup to a public resolver. It will fail and print a confirmation that the network guard is active. This allows you to confirm at any time that no data is leaving your machine.

Supply Chain Integrity for Shared Context: The .agmctx Bundle When you share context with a colleague, you need to be sure it hasn't been tampered with. The .agmctx bundle format is designed for this.

When you run agm export-context --sign --zip:

Checksums First: A checksums.json file is created, containing the SHA-256 hash of every file in the export (the manifest, the vector map, etc.).
Cryptographic Signature: An Ed25519 key pair (generated and stored locally in keys) is used to sign the SHA-256 hash of the concatenated checksums. This signature is stored in signature.bin.
Verification on Import: When agm import-context runs, it performs the checks in reverse order:
It first verifies that the checksum of every file matches the value in checksums.json. If any file has been altered, it fails immediately with exit code 4 (Checksum Mismatch). This prevents wasting CPU cycles on a tampered package.
If the checksums match, it then verifies the signature against the public key. If the signature is invalid, it fails with exit code 3 (Invalid Signature).
This layered approach ensures both integrity and authenticity.

Policy-Driven Operation The tool is governed by a policy.json file in your project's .antigoldfishmode directory. This file is your control panel for the tool's behavior.

Command Whitelisting: You can restrict which agm commands are allowed to run. For example, you could disable export-context entirely in a highly sensitive project.
File Path Globs: Restrict the tool to only read from specific directories (e.g., src and docs, but not dist or node_modules).
Enforced Signing Policies:
"requireSignedContext": true: The tool will refuse to import any .agmctx bundle that isn't signed with a valid signature. This is a critical security control for teams.
"forceSignedExports": true: This makes signing non-optional. Even if a user tries to export with --no-sign, the policy will override it and sign the export.

Transparent Auditing via Receipts and Journal You should never have to wonder what the tool did.

If you find it useful, please consider sponsoring the project: https://github.com/sponsors/jahboukie

I'd love to hear your feedback

Receipts: Every significant command (export, import, index-code, etc.) generates a JSON receipt in receipts. This receipt contains a cryptographic hash of the inputs and outputs, timing data, and a summary of the operation.
Journal: A journal.jsonl file provides a chronological, append-only log of every command executed and its corresponding receipt ID. This gives you a complete, verifiable audit trail of all actions performed by the tool.
This combination of features is designed to provide a tool that is not only powerful but also transparent, verifiable, and secure enough for the most sensitive development environments.

DEV Community: Jeremy Brown

A Technical Deep-Dive for the Security-Conscious