Framer AI AgentsDesign and publish professional sites with AI
Shotgun - AI Cofounder Framework
Don't Build Solo. Let Shotgun Ride Along.
17 followers
Don't Build Solo. Let Shotgun Ride Along.
17 followers
An open-source "operating system" that turns your favorite AI agent into a persistent, personalized virtual cofounder for solo founders. It works on any AI agent, with first-class wiring for Claude Code, Cursor, Antigravity, Gemini CLI, and GitHub Copilot. One line installs it, `shotgun-init` injects the full OS into any folder or existing codebase, you run onboarding once, and from then on the agent knows your venture, remembers everything, builds your product, and keeps your data organized.
I'm a solo founder and my main frustration with AI tools is amnesia: every session starts from zero.
Shotgun is my attempt at fixing that with the simplest possible architecture. One command injects it into any folder; your agent picks it up via the AGENTS.md standard (works on Claude Code, Cursor, Codex CLI, and 28+ others). A SHOTGUN.md file defines a strict operating loop (read memory at session start, log decisions with their reasoning, update open loops at session end), and all state lives in plain markdown files. Memory, a data vault for business files, and per-project code workspaces. The model is swappable because nothing lives in the model. CI validates the whole framework on every push: skill frontmatter, loop routing, and the installer end-to-end.
*The latest updates for Shotgun (V1.6) are now available. Shotgun has been enhanced with additional features, skills, and abilities that are typically priced in the field. This makes Shotgun a standout product in its niche. We encourage you to explore these updates. Cheers!
since you asked for honest feedback - the place i'd expect a weaker model to drift is the memory-write step itself, not the actual work. it'll do the task correctly but skip logging the decision, or compress it down to "did X" with no reasoning, which quietly defeats the whole point once you need to know why a call was made three sessions later. is that step enforced structurally somehow, like blocking session-end until the checklist items in SHOTGUN.md are actually filled in, or does it fully depend on the model choosing to follow the loop on its own?
@galdayan Good catch, this is the right failure mode to probe. Honest answer is NO, session-end isn't structurally blocked. It's a prompt-level contract (RULE 0 marks the protocols as unskippable), and a weak model can drift past a prompt. No markdown file prevents that.
What the design does is make drift visible and repairable instead of impossible, in three layers:
Every write echoes a "📌 Saved: ..." line to the founder, so a skipped write shows up immediately. Decisions use a fixed format (Date / Decision / Why / Revisit-when), so a bare "did X" fails the format.
The doctor skill audits the system against its own contract — index integrity, journal freshness, stale loops, unlogged decisions. v1.5 adds a 0–100 Health Score, so drift shows up as a falling number.
The framework is CI-validated on every push, and the format has a conformance spec, so any harness with hard hooks (e.g. Claude Code hooks) can enforce it structurally.
Bottom line: strong models follow the loop reliably; weak ones need the doctor ritual to catch slippage. Per-harness structural enforcement is on the roadmap.
that makes sense, the visible-and-repairable framing is honest. quick follow up on the health score specifically - when it drops, does anything actually happen (a blocking gate, a forced re-read of the loop) or is it purely diagnostic, something the founder has to notice and act on themselves? a score that only reports without any teeth ends up being one more thing that's easy to ignore under pressure.
@galdayan Mostly diagnostic, with two teeth, and I'll be straight about the gap.
Tooth one: the score isn't computed in isolation, it's the last step of a checkup where the doctor has already fixed every reversible problem it found (rebuilt index, journal roll-up, reindexing) before the number is printed. So a low score means "here's what I couldn't fix without you", not "here's your homework."
Tooth two: the score is appended to memory/metrics.md as a tracked metric, and every decision in memory carries a revisit-when trigger that gets scanned against metrics on each checkup. So "revisit if health drops below 70" is a one-line trigger a founder can attach to any decision, and the system surfaces it as a pending re-decision automatically.
The gap: nothing forces the checkup to run. If the founder never says "checkup", the score never updates and nothing fires. That's the same enforcement boundary as the session-end question — a markdown framework can make neglect visible and cheap to repair, it can't make it impossible. The honest fix is putting the checkup on a cadence (the CEO Weekly ritual runs a metrics pulse weekly), and for harnesses with real hooks, wiring doctor into a scheduled run.
@krishnatejavepa appreciate the straight answer on the gap, most people would've oversold the automation there. one more angle - since the score gets appended to metrics.md every checkup, is there any trend view, like health over the last 10 checkups, or is it always just the latest number sitting next to the last one. asking because a single 62 doesn't tell you much, but a 90 to 62 slide over three weeks is a very different conversation with yourself than a 62 that's been stable the whole time
how does it actually persist context between sessions, does it just dump everything into the repo as markdown or is there a real vector store behind it
@smet1510713 No vector store, on purpose. Memory is plain markdown in the repo, following a formal spec (docs/MEMORY-FORMAT.md). One index file (memory/MEMORY.md) loads at session start; everything else loads lazily by task, so context stays small. Recall is grep plus model-generated synonyms — the model expands "pricing" to "subscription, tier, $", grep does the fast lookup. Semantic search without embeddings.
Why markdown over a vector DB: it's git-versioned, human-readable, diffable, and portable to any agent. A vector DB is a dependency you can't read or review. At founder scale (hundreds of entries, not millions), grep + a good index wins. A consolidation routine compacts the index past ~50 lines so it doesn't degrade.
One line to install and my Claude Code agent actually remembered context across sessions without me re-explaining the project each time. Felt like having a real partner instead of a forgetful tool.
Ran shotgun-init on a side project and the onboarding actually felt like delegating to a real cofounder, not just feeding a chatbot context. The fact that it works across Claude Code and Cursor without rewriting anything is what sold me.
I like that you're treating the AI agent as infrastructure rather than the product itself.
As models become interchangeable, I think the longer-term advantage shifts toward the operating system that preserves context, decisions, and continuity across whichever models people choose to use.
That's a much harder layer to build.
The one-line install plus onboarding flow is genuinely well thought out, makes something this ambitious feel approachable instead of overwhelming.