make-agent

An AI agent powered by Makefile skills. Skills extend the agent with domain-specific instructions and shell tools.

pip install makefile-agent

Requires Python 3.11+ and a working make binary. Uses Anthropic and OpenAI SDKs for model access — set the appropriate provider API key in your environment (for example ANTHROPIC_API_KEY or OPENAI_API_KEY).

make_agent [run] --model MODEL [--prompt PROMPT | --prompt-file FILE]

Without --prompt, the agent starts an interactive full-screen REPL. Press Ctrl-D, /exit, or /quit to leave.

Interactive commands: /help, /export (save conversation to HTML), /stats (token usage totals), /exit, /quit.

Useful keys: Alt+Enter inserts a newline, Ctrl-C cancels an in-flight turn, Ctrl-T focuses transcript view, then Ctrl-P/Ctrl-N moves between turns.

All per-project data lives under ~/.make-agent/:

~/.make-agent/
└── <project-slug>/          # e.g. Users_alice_proj_myapp
    ├── history              # shell input history
    ├── makefile/
    │   ├── SYSTEM.md        # default system prompt (copied from template on first run)
    │   ├── skills/          # skill directories
    │   └── memory.db        # conversation history
    └── logs/
        └── make-agent.log

The project slug is the absolute working-directory path with the leading / stripped and remaining / replaced by _.

Priority order (first match wins):

1. --system PROMPT flag
2. --system-file FILE flag
3. ~/.make-agent/<project>/makefile/SYSTEM.md (created from a bundled template on first run)

Each skill is a directory containing a single skill.mk file.

define DESCRIPTION
Searches files for a text pattern.
endef

.PHONY: search-files

search-files:
	@grep -rn "$$PATTERN" "$$DIR" || echo "No matches found"

The agent invokes targets via make, passing parameters as environment variables ($$PARAM in a recipe becomes $PARAM for the shell). The define DESCRIPTION … endef block is required and shown by list_skills.

execute_skill requires confirmation when a skill is not trusted. In interactive mode, the shell prompts [Y] approve / [N] deny.

Trust sources:

• --trusted-skills all trusts all skills.
• --trusted-skills skill_name trusts all targets in that skill.

Use --disable-builtin-tools to turn off specific tools (or all).

Safety constraints:

• write_file and edit_file are sandboxed to paths inside the current working directory.
• execute_skill blocks dangerous make options (-f/--file, -C/--directory, -I/--include-dir, --eval).

Every conversation turn is persisted to a local SQLite database (memory.db), enabled by default.

The database is created at ~/.make-agent/<project>/makefile/memory.db.

Three additional built-in tools are available:

FTS5 search tips — the search is keyword-based, not semantic:

• Use short keywords: "goal project" not "what is the goal of this project"
• Use OR for broader recall: "goal OR objective OR purpose"
• Stop words (the, of, is, a) are not indexed — omit them
• Fall back to get_recent_messages when you don't know which keywords to search for

When the context window is exceeded the agent automatically compacts conversation history and retries. Two strategies are available via --compact-mode:

• drop (default) — removes the oldest turns, keeping the most recent two.
• summarize — replaces prior turns with LLM-generated summaries, preserving more context at the cost of an extra API call.

Up to 3 compaction attempts are made before the request is aborted.

uv run pytest
uv run ruff check make_agent/
uv run ruff format make_agent/