Atlas Forge

Local-first memory orchestration for AI agents in real repositories.

What's New in 0.4.7

• EN: Curated Superpowers vendor subset for professional profile, smaller and cleaner package surface.
• VN: Bộ vendor đã được curate có chủ đích cho profile professional, giảm nhiễu và nhẹ hơn khi phát hành.
• EN: status --json and verify --json now expose a compact runtime_readiness_dashboard.
• VN: status --json và verify --json đã có dashboard readiness ngắn theo từng runtime.
• EN: Legacy migration hardening for old/large repos with stricter config normalization behavior.
• VN: Tăng độ an toàn migration cho repo cũ/lớn với chuẩn hóa config chặt hơn.

Quick Decision

Need	Command	Expected JSON keys
Init one runtime	npx atlas-forge init --agent codex --json	agent_profile, bootstrap.created, bootstrap.skipped
Init full entry layer	npx atlas-forge init --agent all --json	bootstrap.entrypoints, bootstrap.bridges, bootstrap.external_patch_files
Re-sync safely	npx atlas-forge optimize --agent all --dry-run --json	bootstrap.created, bootstrap.drifted, dry_run
Check workspace health	npx atlas-forge verify --agent auto --json	profile, selected_runtime_ready, runtime_readiness_dashboard, gaps
Check live memory state	npx atlas-forge status --agent auto --json	snapshot, promotion, runtime_readiness_dashboard, entrypoints

One-Page Flow

flowchart LR
  A["init --agent auto/all"] --> B["bootstrap entry layer"]
  B --> C["status / search"]
  C --> D["start"]
  D --> E["implement + add"]
  E --> F["doctor"]
  F --> G["close"]
  G --> H["canonical"]

Loading

Runtime Readiness Dashboard

Use verify --json or status --json and read:

• selected_runtime_ready: runtime currently applied by profile is ready or not.
• professional_kit_ready: full multi-runtime kit readiness in professional mode.
• runtime_readiness_dashboard.summary: quick global count.

Sample shape:

{
  "profile": "professional",
  "selected_runtime": "codex",
  "selected_runtime_ready": true,
  "professional_kit_ready": true,
  "runtime_readiness_dashboard": {
    "selected": { "agent": "codex", "ready": true, "patch_state": "required" },
    "agents": {
      "codex": { "ready": true, "patch_state": "required" },
      "claude": { "ready": true, "patch_state": "required" },
      "gemini": { "ready": true, "patch_state": "required" }
    },
    "summary": { "ready_count": 3, "total": 3, "not_ready": [] }
  }
}

60-Second Quickstart

npx atlas-forge init --agent auto --json
npx atlas-forge status --json
npx atlas-forge start "Implement feature X" --json
npx atlas-forge add --type decision --title "Key decision" --summary "Short reason" --json
npx atlas-forge doctor --json
npx atlas-forge close "Done" --json

Agent Quickstart

Agent	First command	Next command	Expected result
Codex	npx atlas-forge init --agent codex --json	npx atlas-forge verify --agent codex --json	CLI-first flow with readiness dashboard
Claude	af_init	af_status	MCP tools active, snapshot + readiness available
Gemini	npx atlas-forge init --agent gemini --json	npx atlas-forge status --agent gemini --json	Profile-specific docs + stable JSON health

Install

npm install @thaild12042003/atlas-forge

Registry Matrix

Registry	Package	Purpose
npmjs	@thaild12042003/atlas-forge	Standard CLI/MCP usage and CI
GitHub Packages	@thaildhe172591/atlas-forge	Repository package visibility and internal distribution

Publish in 60s

npm run lint
npm test
npm run test:smoke
npm run build
npm_config_cache=/tmp/.npm npm pack --dry-run
npm version patch
git push origin main --follow-tags

Tag push triggers Publish Release Packages workflow:

• publish npmjs package
• publish GitHub Packages package
• create/update GitHub Release

Troubleshooting Order (Auth/Publish)

Step	Symptom	Fix
1	ENEEDAUTH	ensure repo secret NPM_TOKEN exists and workflow uses it for npmjs
2	EOTP	recreate npm token with 2FA bypass enabled for automation
3	npmjs E404 scoped package	use token from owner account of @thaild12042003 scope
4	GitHub Packages missing	verify tagged run succeeded and job has packages: write

CLI Commands

All commands support --json.

Command	Purpose
`atlas-forge init [--agent auto	all
atlas-forge optimize [--agent ...] [--dry-run]	Re-sync managed artifacts without silent overwrite
atlas-forge start <summary>	Open task session
atlas-forge add --title --summary [--type]	Stage memory entry
atlas-forge doctor	Run diagnostics
atlas-forge close <summary>	Close task and promote valid entries
atlas-forge search <query> [--limit]	Search canonical memories
atlas-forge status [--agent ...]	Snapshot + readiness + entry-layer metadata
atlas-forge verify [--agent ...]	Structural checks + readiness checks

Best Skill Stack

Agent	Stack	Best for
Codex	systematic-debugging + writing-plans + verification-before-completion	CLI implementation and release safety
Claude	brainstorming + systematic-debugging + verification-before-completion	MCP-first design and diagnosis
Gemini	writing-plans + clean-code + verification-before-completion	Minimal, structured CLI changes
Cursor	brainstorming + documentation-templates + verification-before-completion	IDE-native build + docs updates
Antigravity	brainstorming + workflow-plan + verification-before-completion	Long-running orchestration tasks

Guides

• Tutorial: TUTORIAL.md
• Release checklist: docs/release-checklist.md
• Support matrix: docs/agents/support-matrix.md
• Prompt kit: docs/agents/prompt-kit.md
• Codex: docs/agents/codex.md
• Claude: docs/agents/claude.md
• Gemini: docs/agents/gemini.md
• Cursor: docs/agents/cursor.md
• Antigravity: docs/agents/antigravity.md

Star History

License

MIT © 2026 thaild12042003