Claude Agent Starter

A production-ready template for building a Claude Code operating agent. Get an autonomous AI coding assistant up and running in under five minutes — with pre-wired hooks, persistent memory, custom skills, secure permissions, and a complete behavioral framework. Works on macOS, Linux, and Windows.

Stop reinventing CLAUDE.md every time you start a new project. This starter gives you the proven structure — identity, prime directives, memory protocols, tool routing, auto-commit hooks, and command guards — that turns Claude Code from a chatbot into an autonomous operator.

What is a Claude Code operating agent?

A Claude Code operating agent is a persistent AI assistant configured to manage your development infrastructure. Unlike a generic chatbot, an operating agent:

• Reads, writes, and edits code across multiple repositories autonomously
• Runs shell commands (git, npm, gh, ssh, deployment scripts)
• Maintains persistent memory between sessions via a structured Obsidian vault
• Dispatches parallel sub-agents for complex tasks
• Auto-commits work after every response so progress is never lost
• Blocks dangerous commands (rm -rf, force pushes, destructive SQL) before they execute
• Follows your behavioral rules — push back on bad ideas, own failures, ship instead of narrating

This repository is the starter template — the proven scaffolding that makes all of that work on day one.

Quick start

macOS / Linux / WSL

git clone https://github.com/psybourg/claude-agent-starter my-agent
cd my-agent
./setup.sh
claude

Windows (PowerShell)

git clone https://github.com/psybourg/claude-agent-starter my-agent
cd my-agent
.\setup.ps1
claude

That's it. The setup script verifies your prerequisites, makes hooks executable, initializes git, and prints the plugin install commands to run inside Claude Code.

Features

• ✅ CLAUDE.md template — Pre-structured with Identity, Prime Directives, Behavioral Rules, Memory System, and Tool Usage sections. Fill in the bracketed placeholders and ship.
• ✅ Auto-commit hook — Every response triggers a git checkpoint. You never lose work to a closed terminal.
• ✅ Bash guard hook — Blocks rm -rf /, git reset --hard, git push --force, DROP TABLE, and other destructive patterns before they execute.
• ✅ Obsidian memory vault — Pre-organized folders for decisions, mistakes, patterns, sessions, and projects. Wikilinks and YAML frontmatter ready.
• ✅ Example skill — A working github-installer skill that classifies and installs plugins, MCP servers, and standalone tools correctly.
• ✅ Two-tier permissions — Project-scoped defaults in settings.json, machine-specific bash allowlist in settings.local.json (gitignored).
• ✅ Cross-platform hooks — Bash versions for Mac/Linux/WSL, PowerShell versions for native Windows. Both included.
• ✅ Hardened .gitignore — Excludes API keys, .env files, SSH keys, cloud credentials, and common secret filenames.
• ✅ MIT licensed — Use it, fork it, ship it.
• ✅ Complete PDF guide — 20-page walkthrough of every concept included in docs/.

Prerequisites

• Claude Code CLI — npm install -g @anthropic-ai/claude-code
• Git — version control
• GitHub CLI (`gh`) — for repo creation (gh auth login)
• Node.js 18+ — runtime for Claude Code
• jq — JSON parser used by the bash hooks
• A Claude subscription — Pro or Max recommended for extended context

What you get

claude-agent-starter/
├── README.md                       This file
├── CLAUDE.md                       The agent's brain — customize this
├── CLAUDE.local.md                 Private notes (gitignored)
├── SECURITY.md                     What the hooks do and don't protect against
├── setup.sh                        macOS / Linux / WSL setup
├── setup.ps1                       Windows PowerShell setup
├── .gitignore                      Hardened for secrets
├── LICENSE                         MIT
├── docs/
│   └── how-to-build-a-claude-code-agent.pdf  Full 20-page guide
├── .claude/
│   ├── settings.json               Permissions, hooks, enabled plugins
│   ├── settings.local.json.example Local bash allowlist template
│   ├── hooks/
│   │   ├── auto-commit.sh / .ps1   Auto-commit after every response
│   │   └── guard-bash.sh / .ps1    Block dangerous commands
│   ├── skills/
│   │   └── github-installer/       Example skill
│   └── agents/                     Custom agent definitions
└── obsidian-memory/
    ├── Index.md                    Memory entry point
    ├── decisions/                  Architecture choices
    ├── mistakes/                   What broke + how to fix
    ├── patterns/                   Approaches that worked
    ├── sessions/                   Per-session logs
    └── projects/                   Per-project context

Installing the recommended plugins

After claude starts, run these slash commands inside the session:

/plugin marketplace add anthropics/claude-plugins-official
/plugin marketplace add anthropics/skills
/plugin marketplace add kepano/obsidian-skills
/plugin marketplace add obra/superpowers-marketplace

/plugin install superpowers@claude-plugins-official
/plugin install code-review@claude-plugins-official
/plugin install document-skills@anthropic-agent-skills
/plugin install skill-creator@claude-plugins-official
/plugin install obsidian@obsidian-skills
/plugin install frontend-design@claude-plugins-official
/plugin install typescript-lsp@claude-plugins-official
/plugin install security-guidance@claude-plugins-official
/plugin install context7@claude-plugins-official
/plugin install double-shot-latte@superpowers-marketplace

/reload-plugins

How this compares to other approaches

The full guide

This repository pairs with How to Build a Claude Code Operating Agent — a 20-page PDF that walks through every concept:

1. What you're building and why
2. Prerequisites and quick start
3. Directory structure
4. CLAUDE.md — the brain
5. Settings and permissions
6. Hooks — automated behaviors
7. Skills — custom capabilities
8. Plugins — the ecosystem
9. Memory system — Obsidian vault
10. Subagents — parallel workers
11. GitHub integration
12. Putting it all together
13. Common mistakes to avoid

Frequently asked questions

What's the difference between a Claude Code agent and a chatbot?

A chatbot answers questions in a conversation that resets every time you close the window. A Claude Code operating agent reads instructions from a CLAUDE.md file at session start, maintains persistent memory in an Obsidian vault between sessions, runs tools and shell commands autonomously, dispatches sub-agents for parallel work, and follows the behavioral rules you define. Same underlying model, different configuration.

Do I need an Anthropic API key?

No. Claude Code uses your Claude.ai subscription (Pro or Max). Run claude after installing the CLI and it walks you through authentication.

Why use Obsidian for memory instead of a database?

Obsidian files are plain markdown on disk. Your agent reads and writes them directly with no special tooling. Wikilinks ([[note]]) automatically track renames. You can browse the vault in Obsidian's GUI for a visual overview. And there are no vendor lock-in concerns — the files work in any markdown editor.

How does the auto-commit hook work?

After every Claude Code response, the Stop hook runs git add -A && git commit -m "auto: checkpoint from agent session". This means every step the agent takes is checkpointed. If a session crashes or you close the terminal, your work is committed. You can roll back to any point with git log and git reset.

What does the guard hook block?

It intercepts every Bash tool call before execution and exits with code 2 (block) if the command matches any of these patterns: rm -rf /, rm -rf ~, rm -rf *, DROP TABLE, TRUNCATE TABLE, git reset --hard, git push --force, format c:, rd /s /q. It's a safety net — read SECURITY.md for details on what it doesn't catch.

Can I run multiple Claude Code sessions in the same project?

No. The auto-commit hook will fire from both sessions, and the agents will write over each other's changes. One session per project directory. Always.

Does this work on Windows?

Yes. The repo includes both bash hooks (for Mac/Linux/WSL) and PowerShell hooks (for native Windows). The Windows setup script automatically rewires settings.json to call the .ps1 versions. WSL2 is still recommended if you can use it — there are fewer edge cases.

How is this different from just writing a CLAUDE.md myself?

You absolutely can, and many people do. This starter saves you the iteration — the structure, hook scripts, permission patterns, gitignore, memory vault layout, and SECURITY notes are all the result of hitting the same problems and learning what works. Clone it, customize the placeholders, and ship.

Is this an official Anthropic project?

No. This is an independent open-source project built by Reid Spachman at ixprt. It's compatible with the official Claude Code CLI from Anthropic but not affiliated.

Can I use this for commercial projects?

Yes. MIT licensed. Use it however you want. Attribution appreciated but not required.

Roadmap

• [ ] GitHub Actions workflow for testing CLAUDE.md changes
• [ ] Pre-built domain-specific CLAUDE.md examples (SaaS, data science, DevOps)
• [ ] Optional MCP server templates (Postgres, Stripe, Vercel)
• [ ] Migration script for existing Claude Code projects

Security

Before customizing and publishing your own version, read SECURITY.md. It covers what the hooks actually do, what the permission model allows, what's gitignored, and what to audit before making your customized version public.

Contributing

Found a bug? Have an idea? See CONTRIBUTING.md. PRs welcome.

Acknowledgements

• Anthropic for Claude Code itself
• Obsidian for the memory file format
• The Claude Code community for hook patterns and plugin ideas

License

MIT © Reid Spachman / ixprt

Keywords: claude code, claude-code, ai agent, ai coding agent, autonomous agent, anthropic, llm agent, claude code template, claude code starter, claude code operating agent, claude code skills, claude code plugins, claude code hooks, claude code memory, obsidian memory, agent infrastructure, developer tools, ai development, persistent ai agent, autonomous coding agent, claude.md template, agentic ai, claude code config, claude code setup.