# Alfred Agent

**Autonomous AI agent runtime — 1,870 lines, 8 source files, 14 tools, multi-provider.**

The standalone agent that powers AI capabilities across Alfred Linux and Alfred IDE. Handles tool-calling loops, multi-provider LLM routing, session persistence, and a 7-section system prompt. Runs as a PM2 service or interactive CLI.

## Architecture

- **Multi-provider**: Anthropic Claude, OpenAI GPT, Groq (via OpenAI-compatible adapter)
- **14 built-in tools**: File I/O, web search, shell execution, code analysis, workflow hooks
- **Session persistence**: Full conversation history stored to disk as JSON
- **7-section system prompt**: Identity, capabilities, tool descriptions, safety guardrails, context, reasoning, output formatting
- **Core loop**: Autonomous tool-calling with reasoning → action → observation cycle

## Source Files (1,870 lines total)

| File | Lines | Purpose |
|------|-------|---------|
| `src/tools.js` | 542 | 14 tool definitions — file read/write, search, shell exec, code analysis |
| `src/hooks.js` | 334 | Lifecycle hooks — pre/post tool execution, response filtering |
| `src/cli.js` | 205 | Interactive CLI with streaming output |
| `src/agent.js` | 196 | Core agent loop — tool calling, reasoning, response synthesis |
| `src/prompt.js` | 174 | 7-section system prompt builder |
| `src/index.js` | 156 | HTTP server (port 3102), health check, message endpoints |
| `src/session.js` | 141 | Session manager with disk persistence |
| `src/providers.js` | 122 | LLM provider abstraction (Anthropic, OpenAI, Groq adapters) |

## Running

```bash
# CLI mode
OPENAI_API_KEY=... node src/cli.js --provider openai --model gpt-4o-mini -m "hello"

# Server mode (PM2)
pm2 start src/index.js --name alfred-agent
# Health: curl http://127.0.0.1:3102/health
```

## Design Decisions

- **No framework**: Pure Node.js, no Express, no LangChain, no abstractions-for-abstractions
- **Provider-agnostic**: Same agent loop works with any OpenAI-compatible API
- **Stateful sessions**: Every conversation persists to `data/sessions/` — no lost context
- **Tool-first**: Agent reasons about WHAT to do, tools handle HOW

## License

AGPL-3.0 — GoSiteMe Inc.