Keep one portable memory-and-skills layer across coding-agent harnesses, so switching tools doesn't reset how your agent works.
A portable .agent/ folder (memory + skills + protocols) that plugs into Claude Code, Cursor, Windsurf, OpenCode, OpenClaw, GitHub Copilot CLI, Google Gemini CLI, Hermes, Pi Coding Agent, Codex, Antigravity, or a DIY Python loop — and keeps its knowledge when you switch.
It also includes a local data layer so you can monitor the whole suite of agents from one place: harness activity, cron runs, active agents, token/cost estimates, KPI summaries, user-defined resource categories, and screenshot-ready daily dashboards.
And it can turn approved, redacted runs into local flywheel artifacts: trace records, context cards, eval cases, training-ready JSONL, and readiness metrics without training a model or sending telemetry.
Minor release. Adds an optional bridge to
codejunkie99/brain, the external
git-backed long-term memory CLI/TUI/MCP server, without vendoring Brain's Rust
workspace into agentic-stack.
agentic-stack brain .... Check Brain status, onboard a project, search global memory, write durable notes, run Brain doctor/TUI, or print the MCP stdio command from the normal agentic-stack CLI.- Project bridge. Installed
.agent/projects now include.agent/tools/brain_bridge.py, so host agents can call Brain explicitly when a task needs cross-project recall. - Brain seed skill. A new
brainskill teaches agents when to query or write Brain memory, and keeps secret handling explicit.
See CHANGELOG.md for the full list.
Minor release. Clears the open PR queue and ships the combined production surface from Copilot CLI, Gemini, Mission Control, and semantic lesson retraction work.
Patch release. Ships the production-ready getting-started guide from PR #49 and fixes onboarding version drift in the first-run banner.
Minor release. Adds agentic-stack upgrade and agentic-stack sync-manifest
so installed projects can pick up new .agent infrastructure and skill
metadata without clobbering adapter settings or user memory.
- Safe upgrade command. Run
agentic-stack upgrade --dry-runto preview skeleton-owned.agentfile updates, thenagentic-stack upgrade --yesto apply them. - Manifest repair. Run
agentic-stack sync-manifestto rebuild.agent/skills/_manifest.jsonlfrom installedSKILL.mdfrontmatter. - No config overwrite. Upgrade leaves
CLAUDE.md,.claude/settings.json, personal/semantic/episodic/working memory, candidates, and existing skill directories untouched. - Stricter doctor.
agentic-stack doctornow warns when Claude Code hook commands point to missing.agentfiles or hook scripts are present but unwired.
Minor release. Adds an opt-in tldraw seed skill for live canvas diagrams and
a skill-local snapshot store. It is beta and off by default.
tldrawseed skill. Draw, diagram, sketch, wireframe, flowchart, and whiteboard on a live canvas athttp://localhost:3030through an MCP server.- Skill-local snapshots. Save worthwhile canvases with
.agent/skills/tldraw/store.py snapshot; list, load, and archive them later without treating them as a fifth memory layer. - Opt-in beta. Onboarding writes
tldraw.enabled: falseby default. After enabling it, users manually mergeadapters/_shared/tldraw-mcp.jsoninto their harness MCP config.
Added two local-first data capabilities for teams running multiple agent
harnesses against the same .agent/ brain.
data-layerseed skill. Generate local dashboard exports across Claude Code, Hermes, OpenClaw, Codex, Cursor, OpenCode, and custom loops: harness events, cron timelines, KPI summaries, token/cost estimates, categories,dashboard.html, anddaily-report.md. The skill also acts as the injected natural-language surface for showing the terminal dashboard.data-flywheelseed skill. Export approved, redacted runs into trace records, context cards, eval cases, training-ready JSONL, and flywheel metrics. It is local-only and model-agnostic; it prepares artifacts but does not train models or call external APIs.
Added the design-md seed skill for root DESIGN.md / Google Stitch
workflows, and fixed the Python 3.9 crash that hit macOS-default brew users
on first run.
Closed the gap between v0.9.0 and a working pi adapter, plus a timezone sweep across every Python writer/reader so the dream cycle stops drifting against the UTC decay window.
Manifest-driven adapter system: every harness is now declared by an
adapter.json, applied by a shared Python backend, and managed via
verb subcommands or an interactive TUI. Cross-platform (POSIX +
Windows) with concurrent-write protection, pre-v0.9 migration via
./install.sh doctor, and shared-file ownership tracking so removing
one adapter never orphans another.
# tap + install (one-time — both lines required)
brew tap codejunkie99/agentic-stack https://github.com/codejunkie99/agentic-stack
brew install agentic-stack
# drop the brain into any project — the onboarding wizard runs automatically
cd your-project
agentic-stack claude-code
# or: cursor | windsurf | opencode | openclaw | copilot-cli | gemini | hermes | pi | codex | standalone-python | antigravity# clone + run the native installer
git clone https://github.com/codejunkie99/agentic-stack.git
cd agentic-stack
.\install.ps1 claude-code C:\path\to\your-projectbrew update && brew upgrade agentic-stack
agentic-stack dashboardgit clone https://github.com/codejunkie99/agentic-stack.git
cd agentic-stack && ./install.sh claude-code # mac / linux / git-bash
# or on Windows PowerShell: .\install.ps1 claude-code
# adapters: claude-code | cursor | windsurf | opencode | openclaw | copilot-cli | gemini | hermes | pi | codex | standalone-python | antigravityAfter the first ./install.sh <adapter>, manage your project with
verb-style subcommands (works with both install.sh and install.ps1):
./install.sh dashboard # TUI dashboard: health, verify, memory, team, skills, instances
./install.sh mission-control # beta local web dashboard; Ctrl-C turns it off
./install.sh brain status # optional external Brain CLI integration
./install.sh add cursor # add a second adapter (Claude Code + Cursor in same repo)
./install.sh status # one-screen view: which adapters, brain stats
./install.sh doctor # read-only audit; green / yellow / red per adapter
./install.sh manage # interactive TUI: header pane + menu loop for add/remove/audit
./install.sh transfer # onboarding-style wizard: export/import memory as a curl bridge
./install.sh upgrade --dry-run # preview safe .agent infrastructure refresh
./install.sh upgrade --yes # copy latest harness/memory/tools + new skills
./install.sh sync-manifest # rebuild .agent/skills/_manifest.jsonl from SKILL.md frontmatter
./install.sh remove cursor # confirm prompt + delete; no quarantine, no undoPowerShell uses the same verbs, for example .\install.ps1 dashboard.
codejunkie99/brain is the
git-backed long-term memory binary and MCP server. agentic-stack now treats it
as an optional external memory layer instead of vendoring its Rust workspace.
Install Brain first:
brew install codejunkie99/tap/brainThen check or wire it from a project:
agentic-stack brain status
agentic-stack brain onboard --agents codex,cursor --yes
agentic-stack brain ask "auth decisions"
agentic-stack brain note "Use PKCE for local OAuth flows."
agentic-stack brain mcp-commandInstalled .agent/ projects also get python3 .agent/tools/brain_bridge.py
and a brain seed skill so host agents can query or write Brain memory when a
task needs cross-harness long-term recall.
Bare ./install.sh (no arguments) opens a multi-select wizard on
a fresh project — check every harness you actually use, hit enter,
each one gets installed. The wizard auto-detects harnesses already on
disk and pre-checks them. On a project that already has an
install.json, bare interactive ./install.sh opens the dashboard.
In non-TTY shells (CI), it stays script-safe and prints the available
subcommands instead of opening a TUI.
Upgrading from pre-v0.9? Run ./install.sh doctor first — it
synthesizes install.json from on-disk adapter signals so the new
backend can track them. Installing on top without migration would
orphan the prior installs.
Upgrading an already-installed project after brew upgrade? Run
agentic-stack upgrade --dry-run in the project first, then
agentic-stack upgrade --yes to refresh only skeleton-owned .agent
infrastructure (harness/**/*.py, top-level memory/*.py, tools/*.py,
the generated skill index, and new skill directories). It does not rewrite
CLAUDE.md, .claude/settings.json, personal/semantic/episodic/working
memory, candidates, or existing skill directories. agentic-stack sync-manifest is available as a repair command if _manifest.jsonl drifts
from installed SKILL.md files.
If you ran bare ./install.sh (no adapter name), the wizard starts
with a multi-select harness step: it lists all 12 adapters, pre-
checks any it detects on disk, and installs each one you confirm with
space + enter. After the install(s), the preferences flow runs.
If you ran ./install.sh <adapter> directly, only the preferences
flow runs.
Either way, the preferences step populates
.agent/memory/personal/PREFERENCES.md — the first file your AI reads
at the start of every session — and writes a feature-toggle file at
.agent/memory/.features.json.
Six preference questions (each skippable with Enter):
| Question | Default |
|---|---|
| What should I call you? | (skip) |
| Primary language(s)? | unspecified |
| Explanation style? | concise |
| Test strategy? | test-after |
| Commit message style? | conventional commits |
| Code review depth? | critical issues only |
Plus one Optional features step (opt-in, off by default):
| Feature | Default |
|---|---|
Enable FTS memory search [BETA] |
no |
Enable tldraw visual canvas [BETA] |
no |
Flags:
agentic-stack claude-code --yes # accept all defaults, beta off (CI/scripted)
agentic-stack claude-code --reconfigure # re-run the wizard on an existing projectEdit .agent/memory/personal/PREFERENCES.md any time to refine your
conventions, or .agent/memory/.features.json to flip feature toggles.
Move the portable parts of one project brain into Codex, Cursor, Windsurf, or a terminal-only project with the onboarding-style TUI:
./install.sh transferThe wizard turns a plain-language intent into a transfer plan, lets you
review target harnesses and memory scopes, blocks secret-like content before
export, and emits a one-line curl command the next environment can run.
For move my memory, it includes preferences, accepted lessons, skills,
working memory, episodic/history logs, and candidate lessons. The importer
unpacks the bundle, verifies its SHA-256 digest, merges preferences and
accepted lessons, copies selected skills, restores selected memory files,
and installs the matching adapter files.
For scripted handoff:
./install.sh transfer export --intent "move my preferences and lessons into Codex" --print-curl
./install.sh transfer import --payload-file transfer.txt --sha256 <digest> --target codexThe nightly auto_dream.py cycle only stages candidate lessons. It
does not mark anything accepted or modify semantic memory. Your host
agent does the review in-session:
# list pending candidates, sorted by priority
python3 .agent/tools/list_candidates.py
# accept with rationale (required)
python3 .agent/tools/graduate.py <id> --rationale "evidence holds, matches PREFERENCES"
# reject with reason (required); preserves decision history
python3 .agent/tools/reject.py <id> --reason "too specific to generalize"
# requeue a previously-rejected candidate
python3 .agent/tools/reopen.py <id>
# retract an accepted lesson from future recall/context (append-only audit)
python3 .agent/tools/retract_lesson.py <lesson_id> --rationale "obsolete after migration"Graduated lessons land in semantic/lessons.jsonl (source of truth) and
are rendered to semantic/LESSONS.md. Rejected candidates retain full
decision history so recurring churn is visible, not fresh. Retracted lessons
stay in history with status=retracted but are excluded from proactive recall.
See docs/architecture.md for the full lifecycle.
Every guide shows the folder structure. This repo gives you the folder structure plus the files that actually go inside: a working portable brain with nine seed skills, four memory layers, enforced permissions, a nightly staging cycle, host-agent review tools, and adapters for multiple harnesses.
- Memory —
working/,episodic/,semantic/,personal/. Each layer has its own retention policy. Query-aware retrieval (salience × relevance); nightly compression into reviewable candidates. - Review protocol —
auto_dream.pystages candidate lessons mechanically. Your host agent reviews them via CLI tools (graduate.py,reject.py,reopen.py) and commits decisions with a required rationale. No unattended reasoning, no provider coupling. - Skills — progressive disclosure. A lightweight manifest always
loads; full
SKILL.mdfiles only load when triggers match the task. Every skill ships with a self-rewrite hook. The bundleddesign-mdskill teaches agents to use a rootDESIGN.mdas the visual source of truth for UI and Google Stitch workflows. - Protocols — typed tool schemas, a
permissions.mdthat the pre-tool-call hook enforces, and a delegation contract for sub-agents. - Data layer — local-only dashboard exports across every harness sharing
.agent/: agent events, cron timelines, KPI summaries, tokens/cost estimates, task categories, harness mix,dashboard.html, and daily report handoff. - Data flywheel — approved, redacted runs can become trace records, context cards, eval cases, training-ready JSONL, and readiness metrics without training a model or sending telemetry.
Per-version release notes live in CHANGELOG.md. The latest release, what broke, what's new, upgrade path, all there.
Opt-in FTS5 keyword search over all memory documents:
# enable during onboarding (or set manually in .agent/memory/.features.json)
python3 .agent/memory/memory_search.py "deploy failure"
python3 .agent/memory/memory_search.py --status
python3 .agent/memory/memory_search.py --rebuildFalls back to ripgrep (rg) if installed, then to grep — both
restricted to .md / .jsonl so source files never pollute results.
The index is stored at .agent/memory/.index/ and gitignored.
.agent/ # the portable brain (same across harnesses)
├── AGENTS.md # the map
├── harness/ # conductor + hooks (standalone path)
│ └── hooks/
│ ├── claude_code_post_tool.py # rich PostToolUse logging (v0.8+)
│ ├── pre_tool_call.py # permissions enforcement
│ ├── post_execution.py # log_execution() entry point
│ └── on_failure.py # failure write + repeated-failure rewrite flag
├── memory/ # working / episodic / semantic / personal
│ ├── auto_dream.py # staging-only dream cycle
│ ├── cluster.py # content clustering + pattern extraction
│ ├── promote.py # stage candidates
│ ├── validate.py # heuristic prefilter (length + exact duplicate)
│ ├── review_state.py # candidate lifecycle + decision log
│ ├── render_lessons.py # lessons.jsonl → LESSONS.md
│ └── memory_search.py # [BETA] FTS5 search (opt-in)
├── skills/ # _index.md + _manifest.jsonl + SKILL.md files
├── protocols/ # permissions + tool schemas + delegation
│ └── hook_patterns.json # user-owned high/medium-stakes regex (v0.8+)
└── tools/ # host-agent CLI + memory_reflect + skill_loader
├── learn.py # one-shot lesson teaching (stage + graduate)
├── recall.py # surface lessons relevant to an intent
├── show.py # colorful brain-state dashboard
├── data_layer_export.py # local cross-harness dashboard/data export
├── data_flywheel_export.py # approved runs -> traces/cards/evals/JSONL
├── brain_bridge.py # bridge to external Brain CLI/MCP memory
├── list_candidates.py
├── graduate.py
├── reject.py
├── reopen.py
└── retract_lesson.py # append-only semantic lesson retraction
adapters/ # one small shim per harness, each with adapter.json manifest
├── claude-code/ (CLAUDE.md + settings.json hooks — $CLAUDE_PROJECT_DIR wired, closes #18)
├── copilot-cli/ (AGENTS.md + .github/instructions/ + .github/hooks/ + .github/skills/ mirror)
├── cursor/ (.cursor/rules/*.mdc)
├── gemini/ (gemini.md + .gemini/skills mirror)
├── windsurf/ (.windsurf/rules/*.md + legacy .windsurfrules)
├── opencode/ (AGENTS.md + opencode.json)
├── openclaw/ (AGENTS.md + system-prompt include; auto-registers per-project agent)
├── hermes/ (AGENTS.md)
├── pi/ (AGENTS.md + .pi/skills symlink)
├── codex/ (AGENTS.md + .agents/skills symlink)
├── standalone-python/ (DIY conductor entrypoint)
└── antigravity/ (ANTIGRAVITY.md)
harness_manager/ # v0.9.0 manifest-driven Python backend
├── schema.py # adapter.json validator (path-safe on POSIX + Windows)
├── install.py # applies file entries per merge_policy
├── state.py # install.json read/write with fcntl/msvcrt locking
├── doctor.py # read-only audit + pre-v0.9 migration synthesis
├── remove.py # safe uninstall with shared-file detection + ownership handoff
├── dashboard_tui.py # project dashboard for health/verify/memory/team/skills/instances
├── mission_control.py # beta local web dashboard entrypoint
├── brain.py # optional external Brain CLI integration
├── mission_control_collectors.py
├── mission_control_render.py
├── mission_control_server.py
├── mission_control_static.py
├── post_install.py # named built-ins (openclaw_register_workspace)
├── manage_tui.py # interactive menu loop for add/remove/audit
├── transfer_tui.py # onboarding-style memory transfer wizard
├── transfer_plan.py # natural-language target/scope planning
├── transfer_bundle.py # export/import bundle codec + merge logic
├── skill_manifest.py # rebuilds skills/_manifest.jsonl from SKILL.md
├── upgrade.py # safe .agent infrastructure refresh
└── cli.py # argparse dispatcher for install.sh / install.ps1
docs/ # architecture, getting-started, per-harness
schemas/data-layer/ # local dashboard/event schemas
examples/data-layer/ # sanitized data-layer shapes
schemas/flywheel/ # data-flywheel artifact schemas
examples/flywheel/ # sanitized approved-run examples
install.sh # mac / linux / git-bash installer (thin Python dispatcher)
install.ps1 # Windows PowerShell installer (thin Python dispatcher)
Formula/agentic-stack.rb # Homebrew formula
CHANGELOG.md # per-version release notes (v0.1.0 onward)
onboard.py # onboarding wizard entry point
onboard_features.py # .features.json read/write
onboard_ui.py # ANSI palette, banner, clack-style layout
onboard_widgets.py # arrow-key prompts (text, select, confirm)
onboard_render.py # answers → PREFERENCES.md content
onboard_write.py # atomic file write with backup
test_claude_code_hook.py # hook validation suite (54 checks)
verify_codex_fixes.py # v0.8.0 regression checks (33 checks)
| Harness | Config file it reads | Hook support |
|---|---|---|
| Claude Code | CLAUDE.md + .claude/settings.json |
yes (PostToolUse, Stop) |
| GitHub Copilot CLI | AGENTS.md + .github/instructions/*.instructions.md |
yes (postToolUse, sessionEnd) |
| Cursor | .cursor/rules/*.mdc |
no (manual reflect calls) |
| Google Gemini CLI | gemini.md + .gemini/skills/ |
no (manual reflect calls) |
| Windsurf | .windsurfrules |
no (manual reflect calls) |
| OpenCode | AGENTS.md + opencode.json |
partial (permission rules) |
| OpenClaw | AGENTS.md (auto-injected) + per-project openclaw agents add --workspace |
varies by fork |
| Hermes Agent | AGENTS.md (agentskills.io compatible) |
partial (own memory) |
| Pi Coding Agent | AGENTS.md + .pi/skills/ + .pi/extensions/ |
yes (tool_result event) |
| Codex | AGENTS.md + .agents/skills/ |
no (manual reflect calls) |
| Standalone Python | run.py (any LLM) |
yes (full control) |
| Antigravity | ANTIGRAVITY.md |
yes (system context) |
- skillforge — creates new skills from recurring patterns
- memory-manager — runs reflection cycles, surfaces candidate lessons
- git-proxy — all git ops, with safety constraints
- debug-investigator — reproduce → isolate → hypothesize → verify
- deploy-checklist — the fence between staging and production
- design-md — uses Google Stitch-style
DESIGN.mdfiles as portable design-system context for UI, frontend, and component work - data-layer — exports local dashboard data, cron timelines, KPIs, and daily reports across harnesses
- data-flywheel — approved runs into context cards, evals, redacted traces, training-ready JSONL, and flywheel metrics
- tldraw — opt-in beta skill for live canvas diagrams with a local
snapshot store under
.agent/skills/tldraw/
- Skills log every action to episodic memory.
auto_dream.pyclusters recurring patterns into candidate lessons.- The host agent reviews candidates with
graduate.py/reject.py. - Graduated lessons append to
lessons.jsonl;LESSONS.mdre-renders. - Future sessions load query-relevant accepted lessons automatically.
on_failureflags skills that fail 3+ times in 14 days for rewrite.git log .agent/memory/becomes the agent's autobiography.- Data-layer exports turn local activity into dashboard-ready monitoring.
- Approved, redacted runs can be exported into
.agent/flywheel/artifacts for retrieval, evals, prompt shrinking, and optional future adapters.
Put sanitized human-approved runs in:
.agent/flywheel/approved-runs.jsonl
Then run:
python3 .agent/tools/data_flywheel_export.pyOutputs land in .agent/flywheel/exports/<date>/:
trace-records.jsonltraining-examples.jsonleval-cases.jsonlcontext-cards/<domain>/<workflow>.mdflywheel-metrics.json
This is local-only and model-agnostic. It creates training-ready artifacts; it does not train a model.
crontab -e
0 3 * * * python3 /path/to/project/.agent/memory/auto_dream.py >> /path/to/project/.agent/memory/dream.log 2>&1auto_dream.py resolves its paths absolutely and performs only mechanical
file operations (cluster, stage, prefilter, decay). No git commits, no
network, no reasoning — safe to run unattended.
Generate a local dashboard for all harnesses writing to the same .agent/
brain:
python3 .agent/tools/data_layer_export.py --window 30d --bucket dayOr let the injected data-layer skill pass the user's words through:
python3 .agent/tools/data_layer_export.py show me last 7 days by hourOutputs land in .agent/data-layer/exports/<date>/, including
dashboard.html, dashboard.tui.txt, and daily-report.md. The command also
prints the onboarding-style terminal dashboard directly inside your coding tool.
Optional local inputs let you add scheduled runs and categories:
.agent/data-layer/cron-runs.jsonl
.agent/data-layer/category-rules.json
.agent/data-layer/harness-events.jsonl
Use this to track crons by day, active agents, token/cost estimates by hour/day/week/month, harness mix across Claude/Hermes/OpenClaw/Codex/etc., success/error rates, run cadence, workflow breadth, and user-defined categories like personal, admin, work, financial, and coding. The data layer is local-only; screenshot delivery requires explicit user approval and a user-configured channel.
See docs/data-layer.md.
Apache 2.0 — see LICENSE.
Based on the article "The Agentic Stack" by @AV1DLIVE — follow for updates and collabs. Coded using Minimax-M2.7 in the Claude Code harness; PR review by Macroscope and Codex. Patterns from Gstack, Claude Code's memory system, and conversations in the agent-engineering community. Built with the hypothesis that harness-agnosticism is the point.