README
¶
Seamark
Stop your AI coding agent from repeating the same mistakes.
Your repository already contains lessons from past bugs, fixes, and code reviews. Seamark brings those lessons into your AI coding agent's next change.
Review proposed lessons, keep the ones that matter, and let Seamark remind your agent when it edits relevant code. MCP tools and agent skills also help it understand past decisions and find related files that may need updating.
What you can do · Get started · Learn from your repository · Agent skills · Documentation
The workspace console (seamark tui, experimental): an installed pin with its evidence, its outcome, and the routes to maintain it.
Why Seamark?
You fix a bug. A reviewer explains the mistake. In the next session, your AI coding agent makes it again. The correction is in your history, but it never reaches the agent when it matters.
Seamark helps you put that knowledge to work:
- Learn from your own repository. Turn past fixes and code review feedback into proposed lessons, with links back to the evidence. You decide what to keep.
- Bring lessons to the next edit. Hooks deliver relevant reminders when your AI coding agent edits matching files, including in a new session.
- Find changes that belong together. Use Git history to spot a generated client, another implementation, or a test that often changes with your code.
- Keep the knowledge with your project. Accepted lessons live in a YAML file you can review and commit. Seamark has built-in integrations for Claude Code and Codex, with a shared framework for adding more AI coding agents.
For example, a reviewer may have explained that changing a backend schema also requires regenerating the frontend client. Seamark can propose a lesson from that feedback and deliver the accepted reminder when the agent edits the relevant code again. You do not have to remember to repeat the correction in every task prompt.
What you can do
After setup, try a command from the table, then open its guide to go further.
| Capability | What it gives you | Try it |
|---|---|---|
| Lessons from your history | Proposed lessons from fix commits and pull-request reviews, each linked to its evidence. You decide which to keep. | seamark index --reviews · Lessons guide |
| Reminders at the edit | Hooks give your AI coding agent an accepted lesson when it edits a matching file, also in a new session. | seamark lessons --file path/to/file · Agent setup |
| Repository evidence over MCP | Five tools tell your agent where to start, why code is there, which files usually change together, and what a diff can reach. | seamark orient · History and analysis |
| Agent skills (optional) | Three skills tell your agent when to use Seamark to explore, plan, and review a change. | seamark init --client claude --skills · Skills guide |
| Workspace console (experimental) | One full-screen view of the index, integrations, evidence, proposals, pins, and settings. Every change starts from a preview. | seamark tui · Console guide |
| Command and diff checks (experimental) | Agent shell commands and diffs checked against a repository policy. New repositories start in warn mode. | seamark check · Policy guide |
| Health and reports | A check of the setup and the index, and a local HTML report of proposals and accepted lessons. | seamark doctor · seamark report --open · Troubleshooting |
Get started
These instructions are for v0.7.0 or newer.
Install the latest published version on macOS or Linux:
brew install seamark-dev/tap/seamark
seamark version
Open a repository with Git history and set up the AI coding agents you use:
cd your-project
# Claude Code
seamark init --client claude --approve-tools
# Codex
seamark init --client codex --approve-tools
# Both, in one run
seamark init --client claude --client codex --approve-tools
This connects Seamark's MCP tools and sets up lesson and command hooks.
--approve-tools adds tool permissions while preserving existing
restrictions; omit it if you prefer to approve each tool call yourself. New
repositories start with command checks in warn mode; they do not block
commands. Existing policy settings are preserved.
The three agent skills are optional. Add --skills to your
setup command, now or later, to install them.
Build the index and check the setup:
seamark index
seamark doctor
Open or restart your AI coding agent in the repository. In Codex, accept the
project trust prompt if you trust the repository, then review the Seamark
hooks with /hooks in the Codex CLI. Tool permissions do not grant hook trust.
See agent setup for compatibility and troubleshooting.
Try asking:
Use Seamark to explain this repository's main areas and recent decisions. Which files often change together?
You should get an overview based on your code and Git history. You can also
run seamark orient yourself. Lesson reminders start when there are relevant
lessons to deliver; the next section shows how to collect them.
Other installation options and setup help →
Learn from your repository
The learning workflow is simple:
Past fixes and reviews → proposed lessons → your review → reminders during edits.
Mine pull-request review comments and fix commits, then list the findings:
seamark index --reviews
seamark lessons --list
Review comments come from GitHub through the GitHub CLI (gh), authenticated
for the repository. Without it, the run keeps the fix commits of local Git
history and reports the reviews as skipped. To stay offline, use
seamark index --fixes-only instead. A new repository or one with little
relevant feedback may have few findings. You can also
write a lesson by hand.
To turn findings into proposed lessons, Seamark can use your installed AI
coding agent CLI. Claude Code is the default. For Codex, set agent.cli: codex
in .seamark/config.yaml as shown in the
inference setup guide.
This is separate from choosing an agent during init.
seamark lessons --distill --dry-run # preview the command and estimated input
seamark lessons --distill --limit 1 # process one group through your AI agent CLI
seamark lessons --proposals # review the proposed lessons and evidence
Lesson generation uses your agent's model access and may incur usage charges. It does not install anything automatically. Review a proposal's wording, evidence, and file scope, then choose its ID:
seamark lessons --apply p1 # replace p1 with an ID you reviewed
By default, this prints a YAML block. Paste it under pin: in
.seamark/lessons.yaml and commit that file to share the lesson. To let
--apply write the file and record the decision for you, enable
distill.write first.
Inspect what applies to a file with seamark lessons --file path/to/file.
Your configured hooks deliver matching reminders during supported edits.
seamark report --open opens a local report of proposals and accepted lessons;
seamark lessons --stats shows which reminders have been delivered.
Learning guide: review, tune, dismiss, and update lessons →
seamark tui (experimental) opens a full-screen console for one workspace:
index state, agent integrations, evidence refresh, distillation runs that
you can stop, proposal decisions, the installed pins with a previewed
retarget or prune, manual pins that you create, edit, or remove, trigger
extraction for the proposals you select, delivery statistics, focused
settings of config.yaml and lessons.yaml (threshold, budgets,
repetition mode, and mutes), a selection sample that compares the
lessons of explicit paths before and after a reviewed change, and doctor
checks. Browsing never writes; every change, fetch, and agent run starts
from a preview that names its exact effects. Workspace console →
Agent skills
Agent skills give your AI coding agent instructions for common tasks. Seamark includes three skills for Claude Code and Codex. They explain when to use Seamark's tools and how to interpret the results.
| Skill | Helps your AI coding agent… |
|---|---|
seamark-understand-repo |
Explore unfamiliar code and understand past decisions. |
seamark-plan-change |
Find related files, possible side effects, and past review feedback before editing. |
seamark-review-change |
Review the diff, check for missed companion files, and revisit relevant lessons. |
For example, when you ask an agent to change an API across several files, the planning skill tells it to check which other files usually change with them. This can reveal a generated client or another implementation that needs attention.
Install them by adding --skills to your setup command, for example
seamark init --client claude --skills. They are optional, and small tasks
such as typo fixes do not require a repository overview.
After upgrading Seamark, repeat your setup command to refresh managed copies.
Skill installation and customization →
MCP tools
MCP (Model Context Protocol) lets your AI coding agent call Seamark for
repository evidence. The setup commands above register the server, which
runs locally as seamark mcp.
| Tool | What it helps answer |
|---|---|
orient |
Where should I start in this repository? |
why |
Why is this code here, what calls it, and what usually changes with it? |
change_set |
What related files and lessons should I check before editing? |
check |
What can this diff affect, and what lessons or related files did I miss? |
expand |
Can I see the source or review findings behind this result? |
The server refreshes the code index when the workspace changes. Refresh
review evidence explicitly with seamark index --reviews or --fixes-only.
Skills guide the workflow; MCP supplies evidence; hooks deliver reminders.
Lessons are advice, and your tests and review still matter.
See it in action
An OpenTelemetry-Go case study follows a real history of histogram bugs: learn that parallel implementations need consistent reset behavior, review the proposed lesson, then deliver it during a later edit.
In the associated controlled benchmark, the agent preserved that behavior in 5 of 5 runs with the lesson delivered at the relevant edit, versus 0 of 5 without it. This result covers one historical task and a fixed model/runtime; it does not predict results for every repository.
Read the case study · Inspect the benchmark
Support and direction
Code analysis supports Go, Python, and TypeScript/JavaScript. Git history analysis works across tracked file types. History is most useful in a repository with enough commits to show recurring patterns.
The current focus is lessons and proposals, MCP tools, and agent skills. Built-in AI coding agent integrations cover Claude Code and Codex, with capabilities and verification limits listed per agent. The shared integration framework makes Seamark independent of any single AI coding agent; support for additional agents requires an adapter.
Policies are experimental and awaiting refinement. Command checks and diff policies are available, but they are not the main onboarding path. See the policy guide before enabling enforcement.
Next, we plan to build on lesson delivery and the agent integration framework with unified hook management. This is future work, not part of v0.8.0. See current status and the changelog.
Privacy and local data
Seamark's code and history index runs locally. Seamark has no account
requirement and sends no telemetry. GitHub review mining uses your gh
login; optional lesson generation uses your AI agent CLI. Evidence provided
through MCP or hooks may also reach your agent's model provider.
See data flow for the details.
Keep .seamark/index.db: it also stores proposal decisions and lesson-generation
history. Use seamark state export to back up that state. Accepted lesson
YAML can be committed separately. Configuration and backups →
Documentation
- Installation and first use
- AI coding agent setup and compatibility
- Lessons and proposals
- Workspace console (experimental)
- Repository history and code analysis
- Configuration and local state
- Data flow and trust boundaries
Contributing
Contributions are welcome. You can improve docs, contribute an AI coding agent integration, or extend the effect catalogue.
Source builds need Go 1.25 or newer and a C compiler:
make test
make lint
make build
make smoke
See the Makefile for additional checks and benchmark commands.
License
Documentation
¶
Overview ¶
Package seamark is the module root. It holds one thing: the agent skills embedded from the skills/ tree. The tree stays at the repository root because `npx skills add seamark-dev/seamark --skill <name>` looks for SKILL.md there. A go:embed directive cannot reach a parent directory, so the embedding package sits beside the tree.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var SkillsFS embed.FS
SkillsFS is the skills/ tree, byte for byte, as built into the binary. The embed directive skips names that start with "." or "_", so the tree must carry none; a test under internal/skills compares the two. internal/skills is the only reader: init, doctor, and status go through it.
Functions ¶
This section is empty.
Types ¶
This section is empty.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
lessons-bench
command
Command lessons-bench runs the active experiment: does the seamark lessons hook change what a headless agent writes? Two arms differing in exactly one bit (the hook wired or absent), a fresh synthetic or pinned-public worktree per trial, a frozen task, and a deterministic judge.
|
Command lessons-bench runs the active experiment: does the seamark lessons hook change what a headless agent writes? Two arms differing in exactly one bit (the hook wired or absent), a fresh synthetic or pinned-public worktree per trial, a frozen task, and a deterministic judge. |
|
lessons-bench-prepare
command
Command lessons-bench-prepare materializes immutable public-repository source and offline dependencies before a lessons benchmark run.
|
Command lessons-bench-prepare materializes immutable public-repository source and offline dependencies before a lessons benchmark run. |
|
lessons-bench-report
command
Command lessons-bench-report renders explicit benchmark JSONL inputs into a deterministic Markdown report evaluated against frozen claims.
|
Command lessons-bench-report renders explicit benchmark JSONL inputs into a deterministic Markdown report evaluated against frozen claims. |
|
seamark
command
Command seamark is the CLI entry point.
|
Command seamark is the CLI entry point. |
|
skills-bench
command
Command skills-bench runs the skills workflow experiment: does installing the seamark agent skills change what a headless agent does on a companion-file task, compared with the seamark MCP server alone? Two arms that differ in exactly one thing (the skills installed and callable, or not), a fresh fixture whose history carries the companion pair, a frozen task, and the lessons benchmark's deterministic judges.
|
Command skills-bench runs the skills workflow experiment: does installing the seamark agent skills change what a headless agent does on a companion-file task, compared with the seamark MCP server alone? Two arms that differ in exactly one thing (the skills installed and callable, or not), a fresh fixture whose history carries the companion pair, a frozen task, and the lessons benchmark's deterministic judges. |
|
skills-bench-report
command
Command skills-bench-report renders workflow result files, and optionally activation result files, into a deterministic Markdown report evaluated against the frozen workflow claims and activation criteria.
|
Command skills-bench-report renders workflow result files, and optionally activation result files, into a deterministic Markdown report evaluated against the frozen workflow claims and activation criteria. |
|
internal
|
|
|
agent
Package agent invokes the user's own coding-agent CLI for one-shot prompted tasks — the inference seam behind features like lesson distillation.
|
Package agent invokes the user's own coding-agent CLI for one-shot prompted tasks — the inference seam behind features like lesson distillation. |
|
approve
Package approve manages the configuration that lets a coding agent call the seamark MCP tools without a permission prompt: Claude Code allow rules in .claude/settings.json and Codex per-tool approvals in .codex/config.toml.
|
Package approve manages the configuration that lets a coding agent call the seamark MCP tools without a permission prompt: Claude Code allow rules in .claude/settings.json and Codex per-tool approvals in .codex/config.toml. |
|
cli
Package cli wires the seamark commands.
|
Package cli wires the seamark commands. |
|
confidence
Package confidence computes a deterministic evidence-health tier for distilled proposals (RFC-002 §6) — a leaf package, because both the distiller's surfaces and the report layer must reach one answer and neither may import the other.
|
Package confidence computes a deterministic evidence-health tier for distilled proposals (RFC-002 §6) — a leaf package, because both the distiller's surfaces and the report layer must reach one answer and neither may import the other. |
|
delivery
Package delivery is the shared advisory-delivery transaction of the edit hooks.
|
Package delivery is the shared advisory-delivery transaction of the edit hooks. |
|
distill
Package distill turns the raw review findings behind lessons into candidate groups for LLM distillation (RFC-001 §5.4 Tier 2).
|
Package distill turns the raw review findings behind lessons into candidate groups for LLM distillation (RFC-001 §5.4 Tier 2). |
|
doctor
Package doctor diagnoses the seamark installation: binary, git, the index database's schema and integrity, policy and effect-catalogue compilation, hook wiring, agent and gh availability, agent skills, tool approvals, and gitignore sanity.
|
Package doctor diagnoses the seamark installation: binary, git, the index database's schema and integrity, policy and effect-catalogue compilation, hook wiring, agent and gh availability, agent skills, tool approvals, and gitignore sanity. |
|
effects
Package effects holds the sink catalogue: which calls can ultimately write a database, spawn a process, touch the filesystem, or leave the network (RFC-001 §5.2).
|
Package effects holds the sink catalogue: which calls can ultimately write a database, spawn a process, touch the filesystem, or leave the network (RFC-001 §5.2). |
|
fixes
Package fixes mines fix commits into findings — the lesson source that exists in every repository, review culture or none.
|
Package fixes mines fix commits into findings — the lesson source that exists in every repository, review culture or none. |
|
gate
Package gate is the pre-execution and pre-edit policy engine (RFC-001 §5.5): commands are parsed with a real shell parser (never regex), classified against the effect catalogue, and evaluated against CEL rules over the declared environment.
|
Package gate is the pre-execution and pre-edit policy engine (RFC-001 §5.5): commands are parsed with a real shell parser (never regex), classified against the effect catalogue, and evaluated against CEL rules over the declared environment. |
|
history
Package history mines the git log into the history layer of the graph: commits become Decision rows, and file co-occurrence across commits becomes CoChange pairs with lift.
|
Package history mines the git log into the history layer of the graph: commits become Decision rows, and file co-occurrence across commits becomes CoChange pairs with lift. |
|
hooks
Package hooks knows how seamark's Claude Code hooks are spelled in .claude/settings.json: the marker strings, the ownership rule, and gate-mode detection live here once — init writes hooks, status reads them, and two copies of the matching logic would drift.
|
Package hooks knows how seamark's Claude Code hooks are spelled in .claude/settings.json: the marker strings, the ownership rule, and gate-mode detection live here once — init writes hooks, status reads them, and two copies of the matching logic would drift. |
|
htmlreport
Package htmlreport renders the index as one self-contained HTML page.
|
Package htmlreport renders the index as one self-contained HTML page. |
|
index
Package index orchestrates a full indexing pass: walk the workspace, parse supported files, resolve call references into edges, mine git history, and write everything into the store atomically.
|
Package index orchestrates a full indexing pass: walk the workspace, parse supported files, resolve call references into edges, mine git history, and write everything into the store atomically. |
|
integration
Package integration holds the client registry and the adapter contracts that make a coding agent (Claude Code, Codex, …) a local contribution: one descriptor, one registration.
|
Package integration holds the client registry and the adapter contracts that make a coding agent (Claude Code, Codex, …) a local contribution: one descriptor, one registration. |
|
integration/inspecttest
Package inspecttest holds the one fixture matrix that the integration, doctor, status, and init tests share.
|
Package inspecttest holds the one fixture matrix that the integration, doctor, status, and init tests share. |
|
learning
Package learning holds the learning-workflow services of the console (`seamark tui`): evidence refresh, distillation, and trigger extraction.
|
Package learning holds the learning-workflow services of the console (`seamark tui`): evidence refresh, distillation, and trigger extraction. |
|
lessonstats
Package lessonstats gathers lesson delivery statistics as typed data for `seamark lessons --stats` and the console.
|
Package lessonstats gathers lesson delivery statistics as typed data for `seamark lessons --stats` and the console. |
|
lsp
Package lsp serves the seamark graph to editors over the Language Server Protocol.
|
Package lsp serves the seamark graph to editors over the Language Server Protocol. |
|
maintain
Package maintain inspects the installed pins and maintains the proposal-linked ones for the console and the CLI.
|
Package maintain inspects the installed pins and maintains the proposal-linked ones for the console and the CLI. |
|
mcp
Package mcp serves the seamark index over the Model Context Protocol's stdio transport: newline-delimited JSON-RPC 2.0, the same hand-rolled approach the LSP server took (RFC-001 §6.2).
|
Package mcp serves the seamark index over the Model Context Protocol's stdio transport: newline-delimited JSON-RPC 2.0, the same hand-rolled approach the LSP server took (RFC-001 §6.2). |
|
model
Package model holds the shared data types of the seamark graph.
|
Package model holds the shared data types of the seamark graph. |
|
outcome
Package outcome implements the passive loop: for each applied pin that has fired at least once, it checks whether the pin's mistake recurred after agents started seeing it.
|
Package outcome implements the passive loop: for each applied pin that has fired at least once, it checks whether the pin's mistake recurred after agents started seeing it. |
|
parse
Package parse turns source files into language-neutral symbol and reference facts.
|
Package parse turns source files into language-neutral symbol and reference facts. |
|
pinfile
Package pinfile reads, classifies, and edits the pin list of .seamark/lessons.yaml.
|
Package pinfile reads, classifies, and edits the pin list of .seamark/lessons.yaml. |
|
pinfile/pinfiletest
Package pinfiletest builds large pin files and the index rows around them, for the Phase 4 benchmarks (make tui-measure).
|
Package pinfiletest builds large pin files and the index rows around them, for the Phase 4 benchmarks (make tui-measure). |
|
proposals
Package proposals is the service layer for the proposal decision ledger.
|
Package proposals is the service layer for the proposal decision ledger. |
|
redact
Package redact scrubs secret-shaped values from text seamark stores or displays: audited command lines (the gate's opt-in raw log), mined review-comment bodies, and fix-commit patches.
|
Package redact scrubs secret-shaped values from text seamark stores or displays: audited command lines (the gate's opt-in raw log), mined review-comment bodies, and fix-commit patches. |
|
render
Package render holds small text-shaping helpers shared by the CLI and LSP surfaces: everything user-visible passes through here so untrusted input (git metadata, source-derived signatures) is handled once.
|
Package render holds small text-shaping helpers shared by the CLI and LSP surfaces: everything user-visible passes through here so untrusted input (git metadata, source-derived signatures) is handled once. |
|
report
Package report renders seamark's text reports — the shared surface behind the CLI, the MCP server, and anything else that answers questions from the index.
|
Package report renders seamark's text reports — the shared surface behind the CLI, the MCP server, and anything else that answers questions from the index. |
|
reviews
Package reviews mines pull-request review comments into lessons: the recurring feedback left on the same kind of change.
|
Package reviews mines pull-request review comments into lessons: the recurring feedback left on the same kind of change. |
|
scaffold
Package scaffold holds the client-independent setup documents and the setup request assembly that `seamark init` and the console share.
|
Package scaffold holds the client-independent setup documents and the setup request assembly that `seamark init` and the console share. |
|
settings
Package settings reads and edits the focused Seamark settings in two documents.
|
Package settings reads and edits the focused Seamark settings in two documents. |
|
skills
Package skills is the catalogue of agent skills that ship inside the seamark binary.
|
Package skills is the catalogue of agent skills that ship inside the seamark binary. |
|
status
Package status gathers and renders the index's semantic health: how much of the workspace is actually covered, how confident the edges are, how old the history evidence is, and which integrations are live.
|
Package status gathers and renders the index's semantic health: how much of the workspace is actually covered, how confident the edges are, how old the history evidence is, and which integrations are live. |
|
store
Package store owns the on-disk index: a single SQLite file holding the structure, history, effects, and policy tables (RFC-001 §5.1).
|
Package store owns the on-disk index: a single SQLite file holding the structure, history, effects, and policy tables (RFC-001 §5.1). |
|
store/storetest
Package storetest builds index rows for the tests of other packages.
|
Package storetest builds index rows for the tests of other packages. |
|
tui
Package tui is the experimental `seamark tui` workspace console.
|
Package tui is the experimental `seamark tui` workspace console. |
|
tui/services
Package services is the typed engine adapter of the seamark console (`seamark tui`).
|
Package services is the typed engine adapter of the seamark console (`seamark tui`). |
|
tui/services/servicestest
Package servicestest holds the fixtures of the tests that run the production engine of internal/tui/services.
|
Package servicestest holds the fixtures of the tests that run the production engine of internal/tui/services. |
|
tui/ui
Package ui holds the drawing primitives of the seamark console: the theme, the glyphs and the tones, the boxes, the modals and the overlay, the text helpers, the scroll, pager and list state, the line input (input.go), the multi-line text area (textarea.go), the movement keys and the n/a key helpers.
|
Package ui holds the drawing primitives of the seamark console: the theme, the glyphs and the tones, the boxes, the modals and the overlay, the text helpers, the scroll, pager and list state, the line input (input.go), the multi-line text area (textarea.go), the movement keys and the n/a key helpers. |
|
wording
Package wording decides whether two short rule/note pairs say the same thing.
|
Package wording decides whether two short rule/note pairs say the same thing. |
|
workspace
Package workspace resolves a repository workspace and describes its index database without writing to it.
|
Package workspace resolves a repository workspace and describes its index database without writing to it. |
|
yamledit
Package yamledit finds the source lines of YAML nodes, so that an editor can splice the text of a committed file instead of encoding it again.
|
Package yamledit finds the source lines of YAML nodes, so that an editor can splice the text of a committed file instead of encoding it again. |