make-agent

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

Installation

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).

Usage

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.

Project data

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 _.

System prompt discovery

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)

Skills

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.

Skill trust and approvals

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.

Built-in tools

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).

Memory

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

Context compaction

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.

Development checks

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