Agent Needle
View repository

Core concepts

Configuration

Set identity, scope, persistence, and local overrides.

Agent Needle separates stable identity from repository-level behavior. Local overrides keep machine details out of shared history.

Identity

.agent/IDENTITY.md describes:

  • Agent name, role, and purpose
  • Operator name, timezone, and preferred language
  • Repository scope and primary responsibility
  • Explicitly out-of-scope work

Do not infer permanent identity or authority from a single request. Replace placeholders before relying on the file.

.agent/IDENTITY.md
## Scope
 
- Repository: `example/service`
- Primary responsibility: API implementation and verification
- Out of scope: Production deployment without approval

Configuration

.agent/CONFIG.md holds defaults for:

Area Default posture
Memory Git-tracked Markdown, relevance-first retrieval, secret redaction
Persistence No automatic commit, push, deploy, or publish
Execution Verify remembered facts, preserve unrelated changes, prefer small complete solutions

Local overrides

Put machine-specific values in .agent/IDENTITY.local.md or .agent/CONFIG.local.md. The supplied .gitignore excludes both.

Local overrides should never contain secrets that an agent does not need. Prefer environment variables or the platform’s secret store for credentials.