Psybourg/claude-agent-starter

O que claude-agent-starter faz?

Modelo de agente Claude Code de nível profissional com hooks, memória persistente, habilidades personalizadas e auto-commit. Crie um agente de codificação autônomo em 5 minutos. macOS, Linux, Windows.

Visão Geral

Este modelo fornece uma base completa para construir agentes Claude Code autônomos, incluindo:

• Hooks: Eventos de ciclo de vida para ações personalizadas antes/depois de tarefas
• Memória Persistente: Estado do agente e contexto preservados entre sessões
• Habilidades Personalizadas: Biblioteca extensível de ferramentas e capacidades
• Auto-Commit: Controle de versão automatizado e gerenciamento de repositório

Começando

Pré-requisitos

• Claude Code CLI instalado (npm install -g @anthropic-ai/claude-code)
• Git 2.30+ instalado
• Node.js 18+ (para scripts auxiliares)

Instalação

git clone https://github.com/Psybourg/claude-agent-starter meu-agente
cd meu-agente
claude-code .

O agente inicializará e executará a configuração inicial automaticamente na primeira execução.

Estrutura do Repositório

.
├── .claude/
│   ├── hooks/           # Hooks do ciclo de vida do agente
│   │   ├── pre-task.sh
│   │   └── post-task.sh
│   └── memory/          # Arquivos de estado persistente
│       └── context.json
├── skills/              # Habilidades personalizadas do Claude Code
│   ├── web-search/
│   │   └── index.ts
│   └── shell-commands/
│       └── index.ts
├── scripts/             # Scripts utilitários
│   └── setup.sh
└── package.json

Hooks

Hooks permitem executar scripts personalizados em eventos específicos do ciclo de vida do agente:

Hook	Acionador	Caso de Uso
pre-task	Antes de cada tarefa	Validação, limpeza de cache, verificação de estado
post-task	Após cada tarefa	Logging, notificações, sincronização de estado
on-error	Em falha de tarefa	Recuperação, relatórios
on-commit	Após auto-commit	CI/CD, implantação

Configuração de Hooks

Edite os scripts em .claude/hooks/ ou adicione novos hooks personalizados.

Memória Persistente

O agente mantém um arquivo de contexto JSON em .claude/memory/context.json. Este arquivo é lido no início de cada sessão e escrito quando o estado muda. A estrutura inclui:

{
  "session": {
    "id": "uuid-v4",
    "startTime": "ISO 8601"
  },
  "project": {
    "name": "meu-projeto",
    "lastTask": "descrição da tarefa",
    "taskCount": 42
  },
  "user": {
    "preferences": {}
  }
}

Habilidades Personalizadas

Habilidades são módulos TypeScript em skills/ que estendem as capacidades do agente. Cada habilidade exporta um objeto SkillDefinition:

interface SkillDefinition {
  name: string;
  description: string;
  execute(args: Record<string, unknown>): Promise<unknown>;
}

Exemplo: Habilidade de Busca na Web

// skills/web-search/index.ts
import { SkillDefinition } from '../../types';

const skill: SkillDefinition = {
  name: 'webSearch',
  description: 'Realiza uma busca na web por consulta e retorna resultados',
  async execute({ query }) {
    // implementação...
    return resultados;
  },
};

export default skill;

Auto-Commit

O recurso de auto-commit cria commits automaticamente em pontos de verificação: (1) quando uma tarefa é concluída, (2) em intervalos de tempo configurados, ou (3) manualmente via comando. As mensagens de commit incluem contexto da tarefa.

Desative com: AUTO_COMMIT=false no seu comando de execução do Claude Code.

Configuração Avançada

Variáveis de Ambiente

Variável	Padrão	Descrição
AUTO_COMMIT	true	Habilitar auto-commit
MEMORY_FILE	.claude/memory/context.json	Caminho do arquivo de memória
HOOKS_DIR	.claude/hooks/	Diretório de hooks

Criação de Hooks Personalizados

1. Crie um novo arquivo de script em HOOKS_DIR (ex: pre-deploy.sh)
2. Torne-o executável: chmod +x .claude/hooks/pre-deploy.sh
3. Registre-o no seu prompt do Claude Code ou trate-o por nome de arquivo

Solução de Problemas

• Erro: 'claude-code' não encontrado: Certifique-se de que npx @anthropic-ai/claude-code está disponível
• Memória não persistida: Verifique se MEMORY_FILE é gravável e em um caminho absoluto
• Hooks não executados: Verifique permissões de execução nos scripts de hook

Licença

MIT - Veja LICENSE para detalhes.