agentmako

agentmako는 AI 코딩 도구를 위한 로컬 우선 코드베이스 인텔리전스 엔진입니다.

Codex, Claude Code, Cursor 및 로컬 하네스와 같은 에이전트가 코드를 수정하기 전에 프로젝트를 이해할 수 있도록 타입이 지정된 MCP 도구 세트를 제공합니다. Mako는 저장소를 인덱싱하고, 로컬 SQLite 기반 팩트를 구축하며, 진단 및 검토 노트를 추적하고, 에이전트가 원시 grep으로 모든 것을 다시 발견하게 하는 대신 구조화된 컨텍스트 패킷을 반환합니다.

Mako는 코딩 에이전트 작업의 첫 단계를 위해 구축되었습니다:

어떤 파일이 중요한가? 어떤 경로, 심볼, 테이블, 진단 및 이전 결과가 관련이 있는가? 에이전트가 다음에 무엇을 읽어야 하는가?

제공 기능

• 코딩 에이전트용 MCP 서버: agentmako mcp

• 로컬 대시보드: agentmako dashboard

• 결정론적 컨텍스트 패킷: context_packet, reef_scout

• 코드 검색 및 구조 도구: cross_search, live_text_search, ast_find_pattern, repo_map

• Reef Engine 인덱싱된 상태, 작업 트리 및 스테이징된 상태 전반에 걸친 팩트 및 결과

• TypeScript, ESLint, Oxlint, Biome 및 스테이징된 git 진단 수집

• 선택적 Postgres/Supabase 스키마 스냅샷 및 읽기 전용 DB 검사

• 테이블, RLS, 트리거, 게시, 구독 및 복제에 대한 메모를 위한 로컬 DB 검토 댓글

• 반복적인 검토 작업을 위한 회상, 승인 및 에이전트 피드백

모든 중요한 작업은 로컬에서 실행됩니다. 호스팅된 서비스는 필요하지 않습니다.

Related MCP server: Context Zero Engine

설치

Node.js 20 이상이 필요합니다.

npm install -g agentmako

CLI 사용 가능 여부 확인:

agentmako doctor

구성 및 로컬 API 서비스에 대한 녹색 체크 표시가 나타나야 합니다.

소스에서 빌드하시겠습니까(예: 기여하기 위해)? 이 파일 하단의 소스에서 개발하기를 참조하세요.

권장 설정 경로

1. 실제 프로젝트 연결

Mako가 이해해야 할 프로젝트로 이동합니다:

cd C:/path/to/your/project

연결 및 인덱싱:

agentmako connect . --no-db

첫 실행 시에는 --no-db를 사용하세요. 데이터베이스 범위를 추가하기 전에 코드 인텔리전스 경로를 먼저 작동시킵니다.

2. Mako가 프로젝트를 인식하는지 확인

agentmako status .
agentmako tool list

실제 스카우트 쿼리 실행:

agentmako --json tool call . reef_scout "{\"query\":\"where should I inspect auth route state?\"}"

순위가 매겨진 후보, 팩트 또는 결과가 반환되면 핵심 설정이 작동하는 것입니다.

3. MCP 클라이언트 구성

MCP 클라이언트 구성에 다음을 추가합니다:

{
  "mcpServers": {
    "mako-ai": {
      "command": "agentmako",
      "args": ["mcp"]
    }
  }
}

MCP 클라이언트를 다시 시작하고 mako-ai 서버가 시작되는지 확인합니다.

에이전트에서 다음 도구 중 하나로 시작하세요:

• 올바른 Mako 도구를 찾아야 할 때 tool_search

• 코딩 작업이 있고 시작 컨텍스트를 원할 때 context_packet

• 순위가 매겨진 프로젝트 팩트/결과/기록을 원할 때 reef_scout

• 자연어 저장소 질문이 있을 때 ask

4. 선택 사항: Claude Code 플러그인 사용

일반 MCP는 Claude Code와 작동하지만, 번들된 플러그인은 Mako 전용 Claude 기술을 추가하고 mako-ai-claude-plugin/.mcp.json에 동일한 agentmako mcp 연결을 포함합니다.

전제 조건:

• Claude Code 설치됨

• PATH에 Node.js 20+ (플러그인이 npx -y agentmako mcp를 실행하며, 이는 게시된 agentmako 패키지를 자동으로 가져옵니다. 별도의 전역 설치가 필요하지 않음)

• agentmako connect로 이미 연결된 대상 프로젝트

agentmako 저장소 루트에서:

claude plugin validate .\mako-ai-claude-plugin
claude --plugin-dir .\mako-ai-claude-plugin

Claude Code 내에서 /mcp를 실행하고 mako-ai가 연결되었는지 확인합니다.

플러그인은 다음 기술을 노출합니다:

• /mako-ai:mako-guide

• /mako-ai:mako-discovery

• /mako-ai:mako-trace

• /mako-ai:mako-neighborhoods

• /mako-ai:mako-graph

• /mako-ai:mako-database

• /mako-ai:mako-code-intel

• /mako-ai:mako-workflow

Claude Code가 어떤 도구를 호출하고 결과를 해석하는 방법에 대한 Mako 전용 지침을 로드하도록 하려면 플러그인을 사용하세요.

5. 선택 사항: 대시보드 실행

대상 프로젝트에서:

agentmako dashboard .

이 명령은 로컬 API, 하네스 서비스 및 웹 대시보드를 시작합니다.

6. 선택 사항: Supabase/Postgres 인식 추가

Mako는 데이터베이스 없이도 작동합니다. 코드 인텔리전스가 작동한 후에만 추가하세요.

일회성 대화형 설정을 위해:

agentmako connect .

환경 변수를 사용하는 CI 또는 스크립트 설정을 위해:

set DATABASE_URL=postgres://...
agentmako connect . --db-env DATABASE_URL --yes

그런 다음 로컬 스키마 스냅샷을 새로 고치고 확인합니다:

agentmako refresh .
agentmako verify .

대화형 모드는 기본적으로 OS 키체인에 데이터베이스 비밀을 저장합니다. 프로젝트 구성은 일반 텍스트 DB URL이 아닌 참조를 저장합니다.

일반적인 일일 루프

대상 프로젝트에서:

agentmako status .
agentmako dashboard .
agentmako --json tool call . context_packet "{\"query\":\"fix the broken auth callback route\"}"

스테이징된 검토 확인을 위해:

agentmako git precommit . --json

데이터베이스 검토 노트를 위해:

agentmako --json tool call . db_review_comment "{\"objectType\":\"replication\",\"objectName\":\"supabase_database_replication\",\"category\":\"review\",\"comment\":\"Check publication coverage before relying on realtime events.\",\"tags\":[\"supabase\",\"replication\"]}"

소스에서 개발하기

Mako 자체를 수정하려면 npm에서 설치하는 대신 복제하고 빌드하세요.

전제 조건:

• Node.js 20 이상

• Git

• Corepack (corepack enable, 최신 Node.js에 포함됨)

git clone https://github.com/drhalto/agentmako.git
cd agentmako
corepack pnpm install
corepack pnpm run build
npm link ./apps/cli

npm link ./apps/cli는 소스 빌드된 CLI를 PATH에서 agentmako로 사용할 수 있게 하여 전역 npm 설치를 대체합니다. 변경 사항을 가져온 후 corepack pnpm run build를 다시 실행하세요.

게시된 버전으로 돌아가려면: npm install -g agentmako.

개발 확인

corepack pnpm run typecheck
corepack pnpm run build
corepack pnpm run test:smoke:reef-tooling
corepack pnpm run test:smoke:reef-model-facing-views

전체 검증:

corepack pnpm test

저장소 레이아웃

apps/
  cli/              agentmako CLI and MCP entrypoint (the published package)
  web/              local dashboard
packages/
  contracts/        public TypeScript contracts and tool schemas
  config/           shared config helpers
  logger/           shared logger
  sdk/              programmatic SDK
  store/            SQLite stores, migrations, and query helpers
  tools/            shared tool implementations
  harness-core/     local agent harness runtime
  harness-tools/    action tools available to the harness
  harness-contracts/ harness contracts and provider catalog
services/
  api/              local API and MCP transports
  engine/           Reef Engine fact/finding pipeline
  harness/          local harness HTTP service
  indexer/          repo and schema indexing logic
  worker/           background worker
extensions/         provider and integration packages
storage/            schema migrations, models, queries
test/smoke/         smoke coverage
mako-ai-claude-plugin/ Claude Code plugin with Mako skills

추가 문서

• 도구 개요

• CLI 문서

• Reef Engine

• Claude Code 플러그인

• CLAUDE.md / AGENTS.md에 붙여넣을 에이전트 지침

• 기여하기

• 보안 정책

• 변경 로그

라이선스

Apache-2.0. LICENSE를 참조하세요.