README
¶
agentic-go
Source-grounded Go intelligence for coding agents.
Website · Docs · Install · Connect · Workflow · Capabilities · FAQ
agentic-go is a local Go MCP server and CLI. It gives an external coding agent semantic context, change continuity, guarded refactoring, and executed verification without embedding an LLM or becoming an agent framework.
The v1.1.0 server exposes 15 MCP tools: the frozen v1 surface of 14 tools plus the additive go_context tool under agentic.focus/v1. The seven resources, resource template, six prompts, and frozen v1 schemas remain unchanged.
Install
On macOS or Linux:
brew install agentic-mcps/tap/agentic-go
agentic-go --version
That installs agentic-go, the pinned agentic-go-gopls companion, and agentic-go-vet. The Homebrew tap is maintained separately; the signed v1.1.0 release archive and checksum installer below are the canonical versioned distribution path.
For an agent workflow, install the binary first, then print the client-native MCP entry for the current workspace:
agentic-go mcp-config --client codex --workspace "$PWD"
The command prints configuration for manual review and copying. It does not edit your client configuration.
Install from the release archive instead
curl -fsSL https://raw.githubusercontent.com/agentic-mcps/go/v1.1.0/scripts/install.sh \
| bash -s -- 1.1.0
The installer places the binaries in ~/.local/bin and verifies the release checksum before replacing them.
Connect
Start agentic-go as a stdio MCP server with your Go workspace as its working directory. The process is local; there is no daemon, port, or hosted account to configure.
Generic MCP entry
{
"mcpServers": {
"agentic-go": {
"command": "agentic-go",
"args": ["--workspace", "/absolute/path/to/your/go/module"]
}
}
}
--workspace defaults to the current directory. The client controls approvals for operations that execute repository code.
Codex users can optionally use the model-invoked project skill at
.agents/skills/agentic-go-context. Keep it in the repository's project skill
path, or install it manually in a user skill directory when needed:
mkdir -p "${CODEX_HOME:-$HOME/.codex}/skills"
cp -R .agents/skills/agentic-go-context "${CODEX_HOME:-$HOME/.codex}/skills/"
This copy is optional and does not edit MCP configuration. The skill only
guides when to call go_context; it does not install the binary.
Workflow
The useful loop is deliberately small: orient, set intent, edit, catch drift, then verify.
For a direct change report:
agentic-go verify --base origin/main --package ./... --format text
The report is conservative, package-aware, and explicit about evidence and uncertainty. It never selects individual tests. JSON output follows agentic.verify/v1; exit 0 means pass, 1 means policy findings, and 2 means incomplete or execution failure.
For focused context before an edit, an MCP client can call go_context with the required local base (for example HEAD or origin/main) and one selector, then refresh after editing with the base and returned pack_id as previous_pack_id only. Stale selectors and refs are rejected. The equivalent CLI command is:
agentic-go context --base origin/main --query Worker --format text
Capabilities
| Area | What the agent gets |
|---|---|
| Workspace context | Package APIs, diagnostics, definitions, references, implementations, related tests, and bounded call relationships. |
| Change continuity | A private contract containing the goal, scope, decisions, questions, drift, and snapshot lineage. |
| Guarded refactoring | Preview or apply deterministic rename, formatting, import organization, and approved source.fixAll edits. |
| Verification | Impact, whole-package tests, coverage, optional race evidence, calibrated findings, contract compliance, and uncertainty. |
Every result is tied to an immutable snapshot. Stale references fail instead of silently moving the goalposts.
FAQ
Does this replace gopls?
No. A pinned gopls sidecar provides semantic capabilities; agentic-go adds snapshots, continuity, guarded mutation, and verification around it.
Can it change my files?
Only an explicitly approved, snapshot-bound deterministic refactor can mutate existing contained non-generated files. Git state never changes.
What does it run?
Execution tools may compile and run trusted repository tests, benchmarks, or fuzz functions with the server process's privileges. Audit tools are read-only. Containment is not a sandbox.
What is supported?
Go 1.25, 1.26, and 1.27 on Darwin and Linux for amd64 and arm64. The release bundles gopls v0.21.0. Newer stable Go versions may pass preflight but are not claimed. The organization module and the former personal module are separate identities with no alias or automatic mirroring.
Maintainer notes: Action and evidence
The optional composite GitHub Action downloads the exact release, verifies its checksum, and writes a job summary plus JSON report. It is advisory by default and requests no pull-request write permission.
The v0.2 evidence records contract goldens, CLI dogfood, release checks, and reviewed historical changes. The v0.1 calibration covered 10 pinned repositories and 467 reviewed findings with 0% observed false positives in that corpus. This is corpus-specific evidence, not a universal guarantee. A private GPT-5.6 Luna focus pilot found no treatment use; its later 27-run adoption follow-up recorded use in 6/6 runs with generic guidance and 6/6 runs with the shipped skill, after 0/6 with description-only discoverability. These records establish observed workflow use and safety, not causal engineering improvement, speedup, token savings, reliability, or general adoption. The bounded paid Codex and Claude comparison has not run; see the adoption evidence.
More
Website · Docs · Contracts · Migration · Roadmap · Contributing · Security · Issues
Artwork and license
The project mark is a supplied adaptation from Maria Letta's Free Gophers Pack, released under CC0. The adaptation is controlled by Ashwin Gopalsamy; the project mark and derived graphics are licensed CC BY 4.0. It is not the official Go logo. Software is available under the Apache-2.0 license.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
agentic-go
command
|
|
|
agentic-go-vet
command
|
|
|
internal
|
|
|
analysis/astutil
Package astutil contains shared, type-aware helpers for analysis passes.
|
Package astutil contains shared, type-aware helpers for analysis passes. |
|
analysis/errors
Package errors implements the mechanical error-handling diagnostics.
|
Package errors implements the mechanical error-handling diagnostics. |
|
changeimpact
Package changeimpact discovers the final local repository snapshot and the conservative Go package closure affected by it.
|
Package changeimpact discovers the final local repository snapshot and the conservative Go package closure affected by it. |
|
cmd/releasepack
command
Command releasepack builds the four supported agentic-go release bundles.
|
Command releasepack builds the four supported agentic-go release bundles. |
|
execution
Package execution runs bounded subprocesses inside a validated workspace.
|
Package execution runs bounded subprocesses inside a validated workspace. |
|
finding
Package finding defines shared structured analyzer output types.
|
Package finding defines shared structured analyzer output types. |
|
gopls
Package gopls manages the pinned semantic-intelligence sidecar over LSP.
|
Package gopls manages the pinned semantic-intelligence sidecar over LSP. |
|
intelligence
Package intelligence provides snapshot-bound, source-grounded Go context.
|
Package intelligence provides snapshot-bound, source-grounded Go context. |
|
parser
Package parser contains bounded decoders for tool output formats.
|
Package parser contains bounded decoders for tool output formats. |
|
progress
Package progress reports advisory MCP progress at real operation milestones.
|
Package progress reports advisory MCP progress at real operation milestones. |
|
releasebundle
Package releasebundle creates reproducible agentic-go release artifacts.
|
Package releasebundle creates reproducible agentic-go release artifacts. |
|
trace
Package trace records optional, privacy-preserving tool-call summaries.
|
Package trace records optional, privacy-preserving tool-call summaries. |
|
verification
Package verification defines and assembles the portable change-verification report shared by the CLI, GitHub Action, and MCP adapters.
|
Package verification defines and assembles the portable change-verification report shared by the CLI, GitHub Action, and MCP adapters. |
|
workspace
Package workspace validates and contains access to a configured Go workspace.
|
Package workspace validates and contains access to a configured Go workspace. |
|
validation
|
|
|
cmd/eval
command
|
|
|
cmd/fpcheck
command
|
|
|
internal/adoption
Package adoption defines the private discoverability experiment contract.
|
Package adoption defines the private discoverability experiment contract. |