If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/x-motemen/gore shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Slowing — last commit 4mo ago

• Last commit 4mo ago
• 2 active contributors
• MIT licensed
• CI configured
• ⚠ Slowing — last commit 4mo ago
• ⚠ Small team — 2 contributors active in recent commits
• ⚠ Single-maintainer risk — top contributor 97% of recent commits
• ⚠ No test directory detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live x-motemen/gore repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/x-motemen/gore.

What it runs against: a local clone of x-motemen/gore — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in x-motemen/gore | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 149 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of x-motemen/gore. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/x-motemen/gore.git
#   cd gore
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of x-motemen/gore and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "x-motemen/gore(\\.git)?\\b" \\
  && ok "origin remote is x-motemen/gore" \\
  || miss "origin remote is not x-motemen/gore (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "cmd/gore/main.go" \\
  && ok "cmd/gore/main.go" \\
  || miss "missing critical file: cmd/gore/main.go"
test -f "gore.go" \\
  && ok "gore.go" \\
  || miss "missing critical file: gore.go"
test -f "session.go" \\
  && ok "session.go" \\
  || miss "missing critical file: session.go"
test -f "commands.go" \\
  && ok "commands.go" \\
  || miss "missing critical file: commands.go"
test -f "gopls.go" \\
  && ok "gopls.go" \\
  || miss "missing critical file: gopls.go"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 149 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~119d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/x-motemen/gore"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Gore is an interactive Go REPL (Read-Eval-Print Loop) that executes arbitrary Go code snippets and expressions in a persistent session using go run under the hood. It combines line editing, code completion via gopls, package auto-importing, and REPL commands (:import, :type, :doc, :print, etc.) to provide a Python-like interactive Go development experience without leaving the terminal. Single-package monorepo: cmd/gore/main.go is the entry point; core session logic in session.go, REPL loop in gore.go, command parsing in commands.go/command_name.go, completion via complete.go/gopls.go, and error filtering in errfilter.go. CLI wrapper in cli/ handles option parsing. Module management via gomod.go.

Go developers who want to experiment with code snippets, test expressions, and explore package APIs interactively without creating temporary files or full programs. Used by developers learning Go, prototyping ideas, and debugging logic in real-time.

Actively maintained with CI/CD via GitHub Actions (.github/workflows/ci.yaml), comprehensive test coverage across core modules, and a Go 1.25 dependency baseline. The README explicitly notes it's mature but slower than alternatives like gomacro/yaegi; production-ready for interactive use but not for performance-critical automation.

Low dependency count (go.lsp.dev/protocol, golang.org/x/tools as primary deps) with quality packages, but single-maintainer risk (motemen-focused). The architecture design re-evaluates all prior input on each new line (see issue #67 in README), which is a known limitation for time-sensitive code. No recent commit data visible, so maintenance status should be verified.

Recent dependency updates visible (motemen/go-quickfix at 2025-02-24, golang.org/x/tools at 0.34.0), suggesting active maintenance. CI runs on commits to main branch. No specific PR or milestone data is visible in provided excerpts.

git clone https://github.com/x-motemen/gore.git
cd gore
go install ./cmd/gore
gore  # Start the REPL

Optionally: go install golang.org/x/tools/gopls@latest for code completion.

Daily commands:

go run ./cmd/gore/main.go
# or after install:
gore

Then enter Go code at the > prompt. Type :help for REPL commands or Ctrl-D to exit.

• cmd/gore/main.go — Entry point for the gore REPL application; every contributor must understand how the CLI is initialized and the main event loop is structured.
• gore.go — Core REPL session logic and interpreter; the heart of the application where user input is evaluated and results are displayed.
• session.go — Session state management including imports, variable scope, and code execution context; critical for understanding how gore maintains state across REPL interactions.
• commands.go — REPL command dispatcher and built-in command implementations (e.g., :import, :doc, :q); essential for extending REPL functionality.
• gopls.go — Language server protocol integration for code completion and documentation; enables the advanced IDE-like features that differentiate gore.
• cli/cli.go — Command-line argument parsing and configuration setup; where user flags and options are processed before session initialization.
• liner.go — Terminal line editing integration using the liner library; provides the interactive prompt and history functionality.

Add a New Built-in REPL Command

1. Define the command pattern in command_name_test.go and add parsing logic to command_name.go (command_name.go)
2. Implement the command handler function in commands.go following the pattern of existing handlers like cmdImport or cmdDoc (commands.go)
3. Update the command dispatch switch statement in gore.go to route the new command (gore.go)
4. Add test cases in commands_test.go to verify command parsing and execution (commands_test.go)
5. Update README.md to document the new command in the REPL Commands section (README.md)

Enhance Code Completion

1. Review the gopls client interface in gopls.go to understand LSP completion requests (gopls.go)
2. Extend the completion filtering and ranking logic in complete.go (complete.go)
3. Integrate new completion sources (e.g., from gomod.go for package names) into the completion workflow (complete.go)
4. Add test cases in complete_test.go to validate completion scenarios (complete_test.go)

Add Support for New Session Options

1. Define the new option as a field in the Options struct in option.go (option.go)
2. Add a flag or configuration method in cli/cli.go to allow users to set the option (cli/cli.go)
3. Use the option in session.go or gore.go during session initialization or evaluation (session.go)
4. Add test coverage in session_test.go or cli/cli_test.go (session_test.go)

Improve Error Messages & Filtering

1. Review current error filtering patterns in errfilter.go (errfilter.go)
2. Add new error patterns to the filter or enhance existing patterns to provide better user feedback (errfilter.go)
3. Integrate quickfix suggestions from quickfix.go for actionable error messages (quickfix.go)
4. Test error scenarios in errfilter_test.go (errfilter_test.go)

• Language Server Protocol (LSP) / gopls — Provides intelligent code completion, documentation lookup, and error diagnostics using Go's official language server without reimplementing parsing/analysis
• Go's AST and go/parser — Enables parsing and analyzing user input to detect statements vs. expressions, auto-import resolution, and code generation
• liner (line editing library) — Provides terminal line editing with history and completion support, improving REPL UX over raw stdin
• go/build and go/mod — Allows dynamic dependency resolution and module-aware compilation in the REPL session
• go-quickfix — Supplies automated error suggestions and fixes to improve error messages and user guidance

• Compile and execute Go code at runtime in a single process

  • Why: Allows for fast iteration and interactive feedback without subprocess overhead
  • Consequence: Code runs in the same address space; malicious or buggy user code can crash the REPL; no isolation guarantees

• Require gopls for advanced features (completion, docs) rather than implementing parsing in-process

  • Why: Avoids duplicating the Go compiler's parsing and symbol resolution logic; stays in sync with official tooling
  • Consequence: gopls must be installed separately; adds latency for LSP requests; increases external dependencies

• Wrap user code in a function and evaluate, rather than executing in a shared namespace

  • Why: Provides clean variable scoping, avoids polluting the global package namespace, enables multi-statement input
  • Consequence: Requires careful state management to persist variables across REPL interactions; adds code generation complexity

• Use os.Osexec to run compiled code rather than embedding a Go runtime

  • Why: Simplifies execution model and avoids reimplementing runtime semantics
  • Consequence: Subprocess overhead; potential security implications for long-running REPL sessions

• Remote or network-based REPL execution (local-only tool)
• Persistence of REPL session state across restarts (ephemeral sessions)
• Real-time collaboration or multi-user REPL sharing
• Web-based or GUI interface (terminal-only)
• Support for non-Go languages or polyglot execution
• Debugger or profiler integration (non-goal; separate tooling)

Re-evaluation gotcha: every new line re-runs all previous lines via go run, so time.Now() is re-evaluated and side effects repeat (see #67 in README). gopls dependency: code completion silently degrades if gopls is not installed (no hard error). Module caching: local go.mod is read at startup; changes during a session are not auto-picked up. Platform differences: terminal_unix.go vs terminal_windows.go handle terminal modes differently—behavior may vary. Temporary files: gore creates temp Go files during execution; if $TMPDIR is unavailable or full, evaluation will fail silently.

• Language Server Protocol (LSP) — Gore uses gopls via LSP (jsonrpc2 transport in go.lsp.dev/jsonrpc2) to request code completions, type info, and diagnostics without parsing Go directly.
• Code Generation and Temporary File Evaluation — Gore's core strategy: it generates temporary Go source files with accumulated code and runs go run on them, then parses output to show results—understanding this is key to debugging evaluation failures.
• Error Filtering / Compiler Error Post-processing — The errfilter.go module strips false-positive errors (e.g., 'declared but not used') that are valid in REPL but invalid in full programs, a critical UX layer.
• Go Module Resolution and Auto-importing — Gore's gomod.go handles dynamic module discovery and downloading (via :import command) within the REPL session, managing go.mod/go.sum for the temp environment.
• REPL Session State Management — The session.go type accumulates source code, imports, and variable bindings across evaluations; understanding its methods (Eval, Source, ImportPackages) is essential for adding new REPL features.
• Terminal Mode Switching (Raw vs Cooked) — Files terminal_unix.go and terminal_windows.go manage entering/exiting raw terminal mode for line editing; cross-platform differences here can cause subtle input/output issues.
• Incremental Compilation and Artifact Caching — Gore re-evaluates all prior code on each new input (the #67 design tradeoff); understanding how go run caches build artifacts helps debug performance and state consistency issues.

• cosmos72/gomacro — Faster Go REPL alternative using bytecode compilation instead of go run, addresses gore's performance limitations mentioned in README
• containous/yaegi — Another Go interpreter/REPL with full expression evaluation without re-running prior code, solves the re-evaluation problem (#67)
• golang/tools — Contains gopls (Language Server Protocol implementation for Go); gore depends on it for completion and diagnostics
• peterh/liner — Pure-Go line editing library that gore uses for history, multi-line input, and terminal interaction (direct dependency in go.mod)
• motemen/go-quickfix — Sibling project by maintainer for applying Go compiler diagnostics; gore uses it to auto-fix import and diagnostic issues

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add integration tests for gopls.go LSP functionality

gopls.go handles Language Server Protocol integration for code completion and diagnostics, but gopls_test.go appears minimal. The repo lacks comprehensive tests for LSP initialization, completion requests, and error handling. This is critical since gopls is a core feature for code completion mentioned in the README.

• [ ] Review gopls.go and gopls_test.go to identify untested code paths
• [ ] Add tests for LSP server initialization and shutdown
• [ ] Add tests for completion request handling with various Go packages
• [ ] Add tests for error cases (missing gopls binary, timeout scenarios)
• [ ] Run tests with go test ./... -v and ensure >80% coverage for gopls.go

Add missing tests for terminal platform-specific behavior (terminal_unix.go, terminal_windows.go)

The codebase has terminal_unix.go and terminal_windows.go for platform-specific terminal handling, but there are no visible test files for these modules. Cross-platform REPL functionality is critical, yet these files lack any test coverage. New contributors can add mock-based tests for signal handling and terminal mode switching.

• [ ] Create terminal_unix_test.go with tests for SIGINT/SIGTERM signal handling
• [ ] Create terminal_windows_test.go with tests for Windows console mode changes
• [ ] Test that terminal restoration works correctly after signal interruption
• [ ] Use build tags (+build unix, +build windows) to conditionally run tests
• [ ] Verify tests run on both platforms in CI (check .github/workflows/ci.yaml)

Add comprehensive tests for gomod.go module management and session_gomod_test.go edge cases

The repo has gomod.go for Go module handling and session_gomod_test.go exists, but given the complexity of module dependency resolution, there are likely untested edge cases. The recent go.mod update to go 1.25 suggests active maintenance. Tests should cover edge cases like circular dependencies, version conflicts, and module cache scenarios.

• [ ] Review gomod.go and identify functions without test coverage (e.g., module version resolution)
• [ ] Expand session_gomod_test.go with tests for: adding conflicting versions, removing modules, and handling go.mod/go.sum inconsistencies
• [ ] Add test fixtures with multiple go.mod scenarios in testdata/
• [ ] Test interaction between gomod.go and the session's package import completion flow
• [ ] Run go test ./... -cover and verify gomod.go coverage exceeds 70%

• Add unit tests for errfilter.go (currently no errfilter_test.go equivalent visible in grep results): write tests covering all error filtering rules to catch regressions in error message sanitization.
• Implement :version REPL command: add a case in commands.go to print gore and Go version, useful for debugging user environments.
• Write integration tests for module auto-import feature in gomod.go: test that :import github.com/some/package correctly downloads and caches modules across sessions.

Gore is a Go REPL tool with generally sound security practices. The codebase uses static linking (CGO_ENABLED=0) and Alpine Linux base image, which reduces attack surface. Primary concerns are: (1) the nature of REPL evaluation allowing arbitrary code execution by design, (2) potential issues with the specified Go version in Docker, and (3) lack of explicit input validation documentation for LSP integration. No hardcoded secrets, SQL injection, or XSS risks were identified. Recommend documenting security implications of REPL usage and adding dependency vulnerability scanning to CI/CD.

• Medium · Outdated Go Version in Dockerfile — Dockerfile. The Dockerfile specifies Go 1.25.5, which appears to be a future/invalid version. Go's versioning typically follows 1.X.Y pattern where X is the minor version (e.g., 1.21, 1.22). This may indicate a typo or misconfiguration that could lead to unexpected behavior or security patches not being applied. Fix: Verify and use a stable, current Go version (e.g., golang:1.21-alpine3.20 or later stable versions). Check the official Go releases for available versions.
• Medium · Potential Command Injection via REPL Input — gore.go, commands.go, session.go. Gore is a REPL that evaluates arbitrary Go code. While this is inherent to the project's functionality, the lack of sandboxing means that any code evaluated in gore could potentially access the filesystem, execute system commands via os/exec, or access network resources. If gore is used in a shared or untrusted environment, this poses a security risk. Fix: Document the security implications clearly. Consider implementing sandboxing or running gore in isolated environments. Add warnings in documentation about not using gore with untrusted input sources.
• Low · Missing Security Headers and Input Validation Documentation — gopls.go, dependencies: go.lsp.dev/jsonrpc2, go.lsp.dev/protocol. While gore is a CLI tool and not a web service, the LSP/JSON-RPC integration (go.lsp.dev packages) communicates over LSP protocol. There is no visible documentation on how input from LSP clients is validated or sanitized. Fix: Review and document LSP input validation. Ensure that JSON-RPC messages are properly validated before processing. Consider adding input size limits and request rate limiting.
• Low · CGO Disabled but No Static Binary Hardening — Dockerfile, Makefile. While CGO_ENABLED=0 is correctly set for static linking, there are no visible compiler flags for enabling security hardening features like -buildmode=pie or ASLR support in the Makefile. Fix: Review Makefile build flags and consider adding security-focused build options: -ldflags '-s -w', -buildmode=pie, and verify runtime security features are enabled.
• Low · No Dependency License Verification — .github/workflows/ci.yaml, go.mod. While dependencies appear legitimate (golang.org/x tools, peterh/liner), there is no evidence of dependency scanning or license compliance checks in the CI/CD pipeline. Fix: Add dependency scanning tools like 'go list -json -m all' with vulnerability checking, consider using 'govulncheck' or similar tools in CI pipeline. Verify licenses are compatible with MIT.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.