Collect →
Import: clients → Hub. Collect MCP definitions, complete skill bundles or selected existing Markdown knowledge. MCP credentials stay in a local .env file.
Client configs stay as they are during import.Local. Transparent. Under your control.
Your agents.
Shared tools.
One Hub.
One shared local Hub for Claude Code, Codex CLI and DeepSeek Harness. Collect existing MCP tools, skills and shared instructions first. Connect individual projects for memory and handoff only when you need them.
01 / understand02 / review03 / apply
YOUR LOCAL SETUPFIG. 01
✳Claude Code~/.claude.json
⌘Codex CLI~/.codex/config.toml
d.DeepSeek Harnessselected DSH profile
Agent Hubtools, context and scoped knowledge
LOCAL
definitionssecret referencesrecovery
Start with ahub quick from any folder. No project path required.
01 / THE BIG PICTURE
Configure once.
Understand every step.
The shared Hub lives at ~/.agent-hub by default. It manages global tools, skills and shared instructions. A project directory is a separate Git repository; connecting its memory is optional.
Compare →
Preview: inspect additions, replacements, conflicts, project scope and affected paths before applying a delivery or memory-onboarding plan.
Quick combines collection and delivery; individual area commands remain available.Apply ↗
Apply: Hub → clients. An explicit revision-guarded command writes changes and a backup. MCP uses the launcher; skills use links; context uses owned instruction blocks.
Restart affected clients after applying. Project memory and hooks use a separate project connect preview.New to MCP? Start here.
MCP is a protocol that lets an AI client connect to external tools and data, such as documentation search or a task board. An MCP server provides those capabilities; Claude, Codex or DSH uses them. Hub manages connection settings and startup. It does not replace models, conversations or external services.
02 / MEMORY ACROSS CLIENTS
Knowledge survives
the client switch.
Claude, Codex and DSH can read the same project facts from Hub through MCP or CLI. Shared knowledge is a separate, explicitly enabled scope. Native notes remain at their original paths.
Find what already exists
Discover client memory directories and their project evidence. Review the selected import; MEMORY.md inline facts are included, while pure local navigation links are omitted. Unresolved sources need an explicit project choice.
Read one current collection
Clients query the same Hub records. A write through Hub is visible on the next read by another client. An existing conversation does not silently refresh knowledge already in its context.
Learn at the end of a task
An enabled lifecycle hook asks the active agent for one evidenced checkpoint, or an empty acknowledgement. It uses the current agent and can add a model continuation; saving still follows client permissions.
What happens automatically?
- With installed hooks and an enabled project policy, SessionStart imports native changes and supplies a bounded project index.
- Stop imports native changes again, then requests one semantic checkpoint. A one-use session token prevents repeat extraction loops.
- An optional foreground watcher imports native file changes between sessions. It is not an installed OS service.
What still needs a reviewed operation?
- Use ahub quick for shared MCP, skills and instruction delivery. Project memory is connected separately.
- ahub project connect reviews a project’s memory, handoff and hooks. The individual memory onboard --follow command only attaches sources; memory auto enable installs hooks separately.
- Manual memory writes and conflict resolution use preview/apply. Incompatible source or Hub edits stay visible as conflicts.
Supported sources and clear limits
Markdown source discovery and import are available. Native SQLite stores are reported but not imported, and external graph-memory interchange and archived-conversation ingestion remain unimplemented. Hub does not mirror records back into every native store. Model-selected facts need a real working trial; protocol tests do not establish their usefulness.
03 / PREVIEW BEFORE APPLYING
No hidden steps.
See what happens.
Switch between common situations to see how Hub explains the outcome.
Interactive illustration. All data is fictional. This site does not run commands or access your computer.
$
Simulation · no real files affected
04 / FIRST RUN
One workflow.
A working Hub.
Install the CLI once, then run ahub quick from any folder. No Git project or workspace is required for the shared Hub. Project memory is a separate optional step. Requires Node.js ≥22.13, npm and a configured client; macOS/Linux are the target platforms.
Get source on GitHubBeta candidate 0.1.0-beta.1 · source 871894b. No public npm release yet.
Releases, packages & checksums →Install ahub once
Open a terminal in the extracted agent-hub directory.
npm ci
npm run install:globalReview the shared Hub plan
Run from any folder. No path or prior init is needed.
ahub quickConfirm, then use your clients
Confirm the reviewed plan in the terminal, then inspect the result. Scripts can use the exact apply command emitted by a noninteractive preview.
ahub status
ahub doctorPrefer an interface?
The shared Hub can be configured from any folder.
ahub uiConnect a project when you need memory
Do this after shared Hub setup. The path is your Git project, not the Hub directory.
ahub project connect /path/to/projectUndo a setup run
Review the pre-run state and confirm in a terminal. Explicit dry runs and scripts remain available.
ahub undo05 / EVERY CAPABILITY
What the command does.
What you get back.
Start with the everyday commands. Advanced operations and client integrations have a separate view; every entry explains its purpose, caller and effects.
For most users, quick and ui are enough. Project memory is optional; status and doctor explain configuration and runtime evidence.
06 / ON YOUR DISK
Your settings.
Ordinary files.
Hub lives in ~/.agent-hub. Set AGENT_HUB_HOME to use another directory. Client directories and the DSH profile can also be configured.
The registry keeps a reference such as ${DOCS_API_TOKEN}. Its value lives in the local .env file and is resolved when MCP starts.
What does startup look like after sync?
The client stores a Node → Hub CLI → mcp run name invocation and AGENT_HUB_HOME instead of copied tokens. The launcher reads the registry and .env. STDIO servers start directly; HTTP/SSE uses a transport bridge. Hub and its CLI must remain available at the configured paths. Memory uses a separate project-bound memory serve process over the same local record service. Native note changes enter Hub at a lifecycle event, a manual import or a watcher scan.
~/.agent-hub/ LOCAL FILESYSTEM
hub.yamlclients, paths and settingsmcp/servers.yamlshared MCP definitions
.envcredentials · mode 0600
state/ownership, backups, doctorskills/ · memory/skill bundles, scoped facts and native source bindings
~/.agent-hub.recovery/baseline and archives · outside Hub
Recovery may contain credentials. Access permissions are restricted; files are not encrypted. Do not upload this directory to Git or a website.
07 / THE WAY BACK
You can go back.
Choose the destination.
Both commands show a plan first. Applying requires an explicit action and a freshness check.
ONE STEP BACK ↶
restore
Undo a specific managed sync, content or memory operation using its backup ID.
node dist/cli.js restore <backup-id> --dry-run- Restore the matching files, memory index and source bindings for that operation.
- Later edits can block an older backup.
- Restart affected clients after applying.
FIRST RECORDED STATE ↺
reset
Return Hub and recorded client configs to their baseline.
node dist/cli.js reset --dry-run- Archive the current state before restoring on apply.
- If Hub originally did not exist, return its path to absence.
- If Hub already existed, restore that checkpoint.
“Before the first run” requires an original state that was actually recorded.
A baseline is captured before the first managed write. If Hub existed before recovery was introduced, its unknown past cannot be reconstructed. Reset refuses to proceed without a baseline; a dry run never creates one retroactively.
External edits, locks and interrupted resets
Manual changes to a client file or its mode block reset. Preview with --archive-changes offers to archive the current file, then restore the original file in full. This is not a merge. A repointed symlink remains a blocker.
Hub uses an external operation lock and recovery journal for interrupted writes. --recover-lock only handles a lock with a provably dead process; live or unknown owners remain protected. I/O failures trigger a compensating rollback attempt. If that also fails, use the retained archives for manual recovery.
Do not run reset alongside active clients or other Hub versions. There is no universal power-loss transaction guarantee, and full preservation of ACLs, xattrs, hardlink identity or arbitrary special files is not promised. Reset does not uninstall the CLI, clear npm cache or undo external API operations.
Managed memory rollback and full reset revoke outstanding checkpoint capabilities. Restored old tokens cannot be replayed; a fresh user prompt can obtain a new checkpoint. Native source notes are not rewritten by memory import.
08 / CURRENT SCOPE
Clear about today.
Honest about tomorrow.
Agent Hub is evolving. This page describes a specific source snapshot rather than a wishlist.
| Area | Today | Implementation boundary |
|---|---|---|
| MCP | Available | Import, shared launcher, sync, diagnostics, backup and recovery. |
| Skills | Available | List/add/remove, client import and canonical link delivery with backups. Discovery and SKILL.md inspection remain available. |
| Shared instructions | Available | Deliver common rules and the shared index through owned blocks, preserving personal text. |
| Scoped memory | Available | Shared/project Markdown records through CLI, local UI and a project-bound Memory MCP server; guarded writes and recovery. |
| Existing-memory import | Available | Discover Markdown sources, review project association and import selected knowledge, including inline MEMORY.md content. SQLite is reported but unsupported. |
| Project automation | Available | Enabled lifecycle hooks, source conflict protection, one semantic checkpoint per user turn and an optional foreground watcher. No installed background service. |
| External graph memory | Planned | No structured graph interchange or live graph mirroring. Archived conversation ingestion is also unimplemented. |
| Repos & tasks | Available | Inspect the current project and run guarded init-repo setup. Existing task notes are preserved; no agent launching. |
| Sessions | Planned | No session index, search or history transfer yet. |
| Additional CLI | Stubs | mcp add/rm are still explicit stubs. |
09 / A FEW MORE ANSWERS
Make the details
make sense.
Plain explanations for beginners. Boundaries and failure behavior for experienced users.
What is the fastest way to get a usable Hub?
Install from the downloaded source using npm ci and npm run install:global, then run ahub quick from any folder or use ahub ui. In a terminal, review the plan and confirm it; restart affected clients. Optional project memory has a separate project connect step. No need to learn individual import, sync or hook commands.
Do I need a workspace to create a Hub?
No. ahub quick prepares the shared Hub without a project or Git repository. The Hub normally lives at ~/.agent-hub. A project directory is only needed for the separate ahub project connect operation, which keeps project knowledge scoped and prepares handoff files. It never means the Hub storage path.
Does this replace Claude, Codex or DSH?
No. Keep using your existing clients. Hub manages their MCP settings and helps expose differences. It does not supply a model, subscription or conversation transfer.
Is this website the local interface?
This website is a guide with a fictional demonstration. It does not read your files. The ui command starts a separate local application with real data and operations on your computer.
What happens to my manual settings?
Sync preserves unrelated MCP entries, other settings and Codex tool policies. Conflicting definitions need a decision. Deleting an entry from the registry only removes an unchanged client entry that Hub previously owned. Review the entire plan. Skills preserve unrelated entries and back up equivalent-copy migrations. Shared context updates only its owned block; project setup preserves existing notes.
Why can doctor pass while a tool still fails?
A successful MCP handshake means initialization and tool discovery worked. Doctor does not call tools/call. A backend, operation-specific authorization or data can still be unavailable. Optional readiness checks separate some of these cases but do not replace functional API checks.
What stops an old plan from being applied?
The revision in --expect checks inputs before writing. A changed file requires a new preview. In the local UI, plans are also single-use and expire after five minutes. Locks and atomic replacement of individual files reduce races; they are not a transaction across your entire computer.
Do credentials have to go to the cloud?
Hub primarily works locally: the registry and .env stay on your machine. Configured MCP processes and endpoints contact their services according to your configuration. Private backups and recovery may contain unencrypted credentials; do not publish them. The local UI does not serve raw .env files and protects write operations.
Can I choose custom directories and profiles?
Yes. Hub: AGENT_HUB_HOME. Claude: CLAUDE_CONFIG_DIR or AGENT_HUB_CLAUDE_CONFIG. Codex: CODEX_HOME. DSH: DSH_HOME and AGENT_HUB_DSH_PROFILE, or a profile in hub.yaml. Shared skills: AGENT_HUB_SHARED_SKILLS. Run status and a fresh preview after changing paths.
Is there automatic sync or a cloud account?
Memory can run automatically after project setup: native imports at SessionStart/Stop and one semantic checkpoint through the active agent. A foreground watcher can scan between sessions. MCP, skills and instruction delivery still use explicit reviewed plans. There is no installed OS service or background cloud sync.
Does existing client memory import into Hub?
Yes, for selected Markdown sources. memory discover lists paths, format and project evidence; memory onboard previews importing existing notes. MEMORY.md inline facts are retained, pure local navigation is omitted, and originals stay unchanged. Ambiguous scope needs an explicit source choice. Native SQLite and graph stores do not have import adapters yet.
What if Claude and DSH change the same fact?
Hub retains source bindings and compares record revisions. An unchanged owned record can update; a divergent duplicate source or a manually edited/deleted Hub record becomes a queued conflict. Inspect both versions, preview keeping Hub or taking the queued incoming value, then apply the exact plan. Incoming history remains available.
Do I need another model or memory database?
No extra model is started for this feature. Markdown records in Hub are the authoritative store and its Memory MCP server exposes the same service. A Stop hook asks the agent already serving your conversation to select evidenced durable knowledge; that can add a model continuation and still follows native tool permissions. It does not reconstruct context the agent has already lost.
Why is following a source different from enabling hooks?
Following attaches a source to the enabled project native-sync policy. It does not install client callbacks. Existing installed handlers can activate for that policy; otherwise review memory auto enable for each client, or run a foreground watcher for file imports. Connecting an MCP server alone does not install lifecycle hooks or guarantee that an agent uses memory.
THE NEXT STEP IS JUST A LOOK