agentsge

Make any project agent-ready with .agents/ directory.

Project intelligence belongs to the project, not the agent. One source of truth — every AI tool reads it.

Quick Start

npx agentsge init

Then open your AI agent (Claude Code, Cursor, Codex, Gemini — any) in the project. It reads AGENTS.md, scans the codebase, asks a few sharp questions, and fills .agents/ with project knowledge.

What happens

1. agentsge init scans the project, detects stack, creates .agents/ with config and capture rules, generates AGENTS.md with onboarding prompt
2. Your AI agent reads AGENTS.md and follows the onboarding steps:
   • Quick scan → updates config.yaml, writes architecture overview
   • Asks 0-3 questions about things it can't find in code
   • Saves answers as knowledge files
   • Replaces AGENTS.md with a clean session-start pointer
3. From now on, _capture.md rule handles ongoing knowledge capture

Commands

agents init              # Initialize .agents/, detect stack, install hooks
agents init --force      # Overwrite existing .agents/

agents sync              # Re-sync entrypoints (with knowledge digest) and MCP configs

agents status            # Show project info, knowledge stats, ref warnings

agents capture list      # Show pending knowledge items
agents capture accept <name>   # Accept pending item into knowledge
agents capture accept --all    # Accept all pending items
agents capture reject <name>   # Delete a pending item
agents capture context         # Output knowledge digest (for debugging)
agents capture context --compact  # Short digest (10-15 lines)

agents hooks install            # Install capture hooks for detected platforms
agents hooks install --agent claude  # Install for specific platform

agents add rule <name>   # Add a new rule
agents add skill <name>  # Add a new skill
agents add mcp <name>    # Add an MCP server (auto-syncs configs)

agents validate          # Validate .agents/ structure and schemas

.agents/ Structure

.agents/
  config.yaml              # Project name, description, stack
  rules/                   # Rules for agents (all mandatory)
    _capture.md            # Built-in: ongoing knowledge capture
  skills/                  # Reusable multi-step workflows
  mcp/                     # MCP server definitions
    config.yaml            # -> synced to .claude/, .cursor/, .codex/
  knowledge/               # Accumulated project knowledge
    _index.md              # Index — always loaded into agent context
    architecture/          # Decisions and trade-offs (WHY)
    patterns/              # Repeating codebase patterns
    lessons/               # Bug investigations, edge cases
    conventions/           # "We do it this way" — not in config files
    dependencies/          # Why X was chosen, known issues

How It Works

AGENTS.md          -> points to .agents/
.agents/           -> single source of truth
  config.yaml      -> project metadata
  rules/*.md       -> mandatory agent rules
  knowledge/       -> accumulated context
  skills/          -> reusable workflows

Every AI agent can read markdown files. No format translation needed — only MCP configs require agent-specific JSON output.

Knowledge System

The _capture.md rule instructs agents to save knowledge when they discover something valuable that a future agent wouldn't find by reading the codebase:

• architecture — decisions, rejected alternatives, trade-offs
• pattern — repeating patterns not obvious from single files
• lesson — bugs where the symptom misled the cause
• convention — team rules that contradict common practice
• dependency — non-obvious choices, known issues, workarounds

Knowledge lives in git. _index.md gives agents instant overview. agents status shows staleness warnings and broken refs.

MCP Sync

Define MCP servers once in .agents/mcp/config.yaml, sync to all agent formats:

agents add mcp postgres
agents sync

Generates: .claude/settings.json, .cursor/mcp.json, .codex/mcp.json, .github/copilot-mcp.json

Stack Detection

The scanner auto-detects:

• Language (TypeScript, Python, Rust, Go, Java)
• Framework (Next, Expo, React, FastAPI, etc.)
• Testing (Vitest, Jest, pytest, etc.)
• Package manager (npm, pnpm, yarn, bun, pip, cargo)
• Monorepo structure (workspaces, multiple frameworks)

Automatic Knowledge Capture

When hooks are installed, agentsge captures knowledge automatically:

1. Session start — saves git HEAD marker, injects knowledge digest into agent context
2. File edits — logs changed files (fast, no LLM, <10ms per event)
3. Session end — collects diff since marker, extracts knowledge via LLM, saves to pending/

Pending items require review before entering the knowledge base:

agents capture list              # See what was captured
agents capture accept --all      # Accept into .agents/knowledge/
agents capture reject bad-one    # Discard

Accepted items are moved to .agents/knowledge/<type>/, added to _index.md, and included in future context digests.

Context Injection

Three levels of recall guarantee:

Level	Mechanism	Guarantee	Works with
Entrypoint	Inline digest in CLAUDE.md / .cursorrules	~95% — always in context	All agents
SessionStart hook	Full digest injected as systemMessage	~99% — agent sees it	Claude, Cursor, OpenCode
beforeSubmitPrompt	Compact digest on every prompt	100% — cannot be skipped	Claude Code

agents sync regenerates entrypoints with the latest knowledge digest. Hooks inject context at runtime.

Supported Platforms

Platform	Hooks support	Config location
Claude Code	sessionStart, postToolUse, stop	.claude/settings.local.json
Cursor	sessionStart, postToolUse, stop	.cursor/hooks/hooks.json
Git (fallback)	post-commit	.git/hooks/post-commit
Copilot	planned	—
OpenCode	planned	—
Gemini CLI	planned	—
Codex CLI	planned	—

Requirements

Node.js >= 22

License

MIT

---

Created by Dali Agents · Production AI agents for support, sales, and ops.