Skip to content

Configuration

Configuration is intentionally file-based and local. Most projects can start with defaults, then tune ignore rules and scoring weights when ranking needs calibration.

Configuration

.agentpack/config.toml:

[project]
root = "."
ignore_file = ".agentignore"

[context]
default_budget = 40000
default_mode = "balanced"  # lite | balanced | deep
max_file_tokens = 4000
min_summary_score = 60
max_summary_files_lite = 15
max_summary_files_balanced = 40
max_summary_files_deep = 0
include_tests = true
include_configs = true
include_receipts = true
broad_context = "auto"       # auto | off | on
broad_context_budget_pct = 35
max_module_summaries = 30
max_inventory_files = 250
memory_feedback = "auto"     # auto | off
memory_boost_weight = 12.0

[context_lite]
budget = 8000
max_selected_files = 12
max_omitted_files = 5
max_stubs = 8
summary_chars = 500

[hooks]
task_switch_detection = true
task_switch_min_terms = 1
blocking_task_refresh = false

[learning]
markdown_output = ".agentpack/learning.md"
daily_output = ".agentpack/daily-summary.md"
skill_map_output = ".agentpack/skills-progress.json"
agent_lessons_output = ".agentpack/agent-lessons.md"
llm_prompt_output = ".agentpack/learning.prompt.md"
pr_comment_output = ".agentpack/pr-learning-comment.md"
feedback_output = ".agentpack/learning-feedback.jsonl"
ranking_feedback_output = ".agentpack/ranking-feedback.jsonl"
episodic_cases_output = ".agentpack/episodic-cases.jsonl"
task_starts_output = ".agentpack/task-starts.jsonl"
procedures_output = ".agentpack/procedures.jsonl"
memory_edges_output = ".agentpack/memory-edges.jsonl"
dashboard_output = ".agentpack/learning-dashboard.html"
team_lessons_output = ".agentpack/team-lessons.md"
provider_command = ""
provider_timeout_seconds = 60
inject_agent_lessons = true
max_changed_files = 20
max_diff_chars_per_file = 1200
max_cards = 5
max_quiz_questions = 5
min_groundedness_score = 70

[runtime]
pack_registry_output = ".agentpack/pack-registry.json"
session_events_output = ".agentpack/session-events.jsonl"
observer_events_output = ".agentpack/observer-events.jsonl"
observer_brief_output = ".agentpack/observer-brief.md"
max_registry_records = 200
max_retrieve_chars = 20000
max_output_summary_items = 40
max_session_events = 2000
max_episodic_cases = 1000

[agents.claude]
output = ".agentpack/context.claude.md"
patch_claude_md = true

[agents.generic]
output = ".agentpack/context.md"

broad_context = "auto" keeps normal coding tasks compact, but adds curated repo-wide inventory and module summaries when the task asks for review, sharing, audit, or repository overview. Existing repos do not need to add these keys; AgentPack uses model defaults when keys are absent.

memory_feedback = "auto" lets prior ranking feedback and episodic eval outcomes provide small, receipt-backed ranking boosts. Episodic boosts are ignored when the remembered file is missing or its recorded hash no longer matches the current checkout. Set it to "off" for baseline comparisons or if local memory becomes noisy.

Task-start snapshots, procedures, and memory edges are local append-only artifacts. They let AgentPack connect task context to code locations and prior validated work while keeping live source and tests authoritative. Memory records carry hashes, provenance, confidence, and visible reasons; stale records remain hints.

max_session_events and max_episodic_cases are retention limits used by agentpack memory --prune. Existing repos receive these defaults at runtime even if their checked-in config file does not yet include the keys.

Loop automation is local and opt-in per runner:

[loop]
enabled = true
runner = ""
runner_adapter = ""
runner_prompt_output = ".agentpack/loop_runner_prompt.md"
max_iterations = 10
verification_commands = []
acceptance_checks = []
require_verification = true
require_progress_update = true
require_clean_tree = true
runner_timeout_seconds = 600
verification_timeout_seconds = 600
max_repeated_failures = 3
risk_sensitive_globs = []
risk_high_file_count = 20

runner is intentionally empty by default. Set it to a local command such as claude < .agentpack/context.claude.md, then set verification_commands to the smallest commands that prove the task. During agentpack work --run, AgentPack captures loop phases, runner JSON contracts, dirty-diff snapshots, verification results, risk reviews, rollback patches, acceptance summaries, handoff notes, and failure diagnoses under .agentpack/. runner_adapter may be claude, codex, or cursor; the adapter only resolves a local command when the matching executable is present. acceptance_checks asks the runner to report semantic pass/fail evidence in its final JSON. risk_sensitive_globs and risk_high_file_count tune the high-risk finish gate for a repo.

Hook defaults stay lightweight. Prompt-submit hooks do nothing until .agentpack/task.md contains a real task, and blocking_task_refresh = false keeps refresh work off the prompt path unless you explicitly opt in.

Configurable scoring weights

# .agentpack/config.toml
[scoring]
modified                  = 100
staged                    = 90
filename_keyword          = 80
symbol_keyword            = 70
content_keyword_per_hit   = 10
content_keyword_max       = 60
direct_dep                = 50
reverse_dep               = 40
related_test              = 35
knowledge_file            = 30   # DECISIONS.md, ADR-*.md, ARCHITECTURE.md, docs/adr/ etc.
config_file               = 25
recently_modified         = 20
churn_high                = 15   # top 10% by commit frequency
large_unrelated_penalty   = -50
ignored_penalty           = -100

Learning

[learning]
markdown_output = ".agentpack/learning.md"
daily_output = ".agentpack/daily-summary.md"
skill_map_output = ".agentpack/skills-progress.json"
agent_lessons_output = ".agentpack/agent-lessons.md"
llm_prompt_output = ".agentpack/learning.prompt.md"
pr_comment_output = ".agentpack/pr-learning-comment.md"
feedback_output = ".agentpack/learning-feedback.jsonl"
dashboard_output = ".agentpack/learning-dashboard.html"
team_lessons_output = ".agentpack/team-lessons.md"
provider_command = ""
provider_timeout_seconds = 60
inject_agent_lessons = true
max_changed_files = 20
max_diff_chars_per_file = 1200
max_cards = 5
max_quiz_questions = 5
min_groundedness_score = 70

These settings control local learning output size, destinations, future-agent context injection, and the quality warning threshold. The quality score includes claim-level citation coverage: generated summaries, decisions, risks, tests, lessons, cards, topics, and skill evidence should cite source files with line anchors where available. Learning artifacts are local by default: no hosted service is called, diffs are bounded, and secret redaction runs before diff text is used. provider_command is opt-in and runs a local JSON-in/JSON-out command with the bounded report payload on stdin. Feedback-aware skill memory and practice drills are stored locally in skill_map_output and feedback_output; shared team learning should export only selected lessons or taxonomy files, not personal skill history. Use dashboard_output for the local IDE/browser review surface and team_lessons_output for shareable lessons that are safe to discuss in review without exposing the developer's personal skill map.

.agentignore

Works like .gitignore. Default rules exclude:

  • node_modules/, .venv/, __pycache__/
  • dist/, build/, .next/, coverage/
  • *.lock, *.log, *.min.js, *.map
  • .env, .env.*, *.pem, *.key
  • *.csv, *.jsonl, *.parquet

Use automation before hand-tuning ignore rules:

agentpack ignore suggest
agentpack ignore apply          # dry-run
agentpack ignore apply --yes    # write reviewed suggestions
agentpack diagnose-selection

Git integration

.agentignore              ✓ commit
.agentpack/config.toml    ✓ commit
.agentpack/cache/         ✓ commit if --share-cache (recommended for teams)
.agentpack/.gitignore     ✗ gitignored
.agentpack/snapshots/     ✗ gitignored
.agentpack/context.*      ✗ gitignored
.agentpack/task.md        ✗ gitignored (local current task)
.agentpack/learning-sessions.jsonl ✗ gitignored (local coach queue)
.agentpack/learning.md    ✗ gitignored (local learning notes)
.agentpack/daily-summary.md ✗ gitignored (local daily rollup)
.agentpack/skills-progress.json ✗ gitignored (local skill evidence)
.agentpack/agent-lessons.md ✗ gitignored (future-agent lessons)
.agentpack/learning.prompt.md ✗ gitignored (optional LLM prompt)
.agentpack/pr-learning-comment.md ✗ gitignored (optional PR summary)
.agentpack/learning-dashboard.html ✗ gitignored (optional local dashboard)
.agentpack/team-lessons.md ✗ gitignored (optional shared lesson export)
.agentpack/learning-feedback.jsonl ✗ gitignored (local feedback)
.agent/skills/agentpack/  ✗ gitignored (generated Antigravity context)

File scoring

Signal Points
Modified file +100
Staged file +90
Filename/path keyword match +80
Symbol keyword match +70
Content keyword match +60
Direct dependency of changed file +50
Reverse dependency +40
Has related tests +35
Knowledge/architecture doc (DECISIONS.md, ADR-*.md, ARCHITECTURE.md, docs/adr/, docs/decisions/, docs/rfcs/) +30
Config file +25
Recently modified +20
High churn (top 10% by commit frequency) +15
Large unrelated file −50
Ignored/binary −100

Keyword scoring uses weighted concept synonym expansion — literal task terms are strongest, normalized variants are slightly weaker, and broad concept synonyms are weaker again. "rate limiting" still expands to throttle, leaky, bucket, quota, but broad expansions no longer dominate literal task terms. Matching is token-based, so task does not accidentally match every tasks.py.