📖 O que é, em 1 parágrafo
iAmasters OS é um repositório open-source com licença MIT,
escrito em português, que entrega um Agentic OS multi-cliente nativo
— não um cliente único depois adaptado, mas pensado desde o primeiro commit para um operador
atender N contas. Vem com a Sinapsis v4.5 embedded
(engine de memória semântica que evolui com o uso), mantido por
Angel Aparicio dentro da
IA Masters Academy. Versão atual:
v0.6.0. Pin de vendor permitido via subpasta
vendor/sinapsis.
📌 A frase que resume o projeto
"Não é um framework para construir agentes. É a casa pronta onde um consultor coloca 30 clientes sem precisar pensar em encanamento."
Linha do tempo do projeto
Janeiro 2026 — Esqueleto
Estrutura de pastas, CLAUDE.md base, 1 cliente exemplo. Sinapsis ainda externa via npm.
Março 2026 — Multi-cliente real
Isolamento por cliente, hooks de redact, primeira release com 3 clientes-piloto em produção.
Abril 2026 — Sinapsis embedded
Engine de memória copiada para vendor/sinapsis. Versão travada, atualização opt-in.
Maio 2026 — Atual
Install em 60s via bun run install-dream, Keychain integrado, launchd templates, skills curadas.
MIT — fork sem culpa.
Português nativo. Não é tradução.
Sinapsis v4.5 embedded.
Angel Aparicio / IA Masters.
👥 Para quem foi feito
Existe um perfil específico que o iAmasters OS atende — e outros perfis para quem o projeto é overkill. Entender isso antes de instalar evita 2 semanas de frustração. O alvo é o operador: pessoa ou time que vende serviços de IA para múltiplos clientes externos.
🎭 Operador vs. dev solo
| Dimensão | Operador (alvo) | Dev solo (não-alvo) |
|---|---|---|
| Clientes ativos | 5 a 30 | 1 (você mesmo) |
| Faturamento por cliente | R$ 2k–20k/mês | N/A |
| Tipo de trabalho | Automação, conteúdo, suporte | Projeto pessoal |
| Isolamento de dados | Crítico (LGPD/contrato) | Irrelevante |
| Onboarding por cliente | Repetível e barato | Único |
| Stack | Claude Code + Sinapsis + skills | Editor + Chat |
✓ Use se você é
- ✓Consultor de IA com carteira (5+ clientes pagantes).
- ✓Agência boutique que entrega automação como serviço.
- ✓Freelance que cobra retainer mensal por operação de agentes.
- ✓Time pequeno (2–6 pessoas) atendendo múltiplas contas.
✗ Não use se você é
- ✗Dev solo otimizando seu workflow pessoal (vai pesar à toa).
- ✗Empresa grande com squad dedicado (monte o seu, mais flexível).
- ✗Curioso sem clientes reais — não testa nada do que importa.
- ✗Usuário Windows sem WSL (suporte é macOS-first, Linux degradado).
Consultor multi-cliente.
Agência boutique.
Freelance retainer.
5–30 clientes ativos.
🧱 As 2 camadas que formam o OS
iAmasters OS não é um monolito. São duas camadas independentes que conversam por convenção: skills curadas (o "userland") e Sinapsis engine (o "kernel" de memória). Você pode trocar uma sem mexer na outra — é isso que dá longevidade ao stack.
📦 Camada 1 — Skills curadas
Vivem em .claude/skills/ por cliente.
Cada skill é um Markdown com frontmatter + instruções. Ativa por trigger no prompt.
- • Local: repo do cliente, versionada em git.
- • Escopo: 1 skill = 1 tarefa repetível.
- • Curadoria: aprovada antes de virar default.
- • Reuso: ~70% das skills servem >1 cliente.
🧠 Camada 2 — Sinapsis engine
Vive em ~/.claude/vendor/sinapsis/.
Memória semântica persistente, indexação automática de sessões, recall por relevância.
- • Local: home do operador, isolado do cliente.
- • Escopo: aprendizado do operador, não do cliente.
- • Versão: v4.5 embedded, pin opcional.
- • Privacy: redact automático antes de indexar.
Exemplo de skill curada (formato real)
# .claude/skills/relatorio-semanal-cliente-x.md --- name: relatorio-semanal description: Gera relatório semanal pro cliente X em formato PDF trigger: "gera o relatório da semana" scope: cliente-x --- # Relatório Semanal — Cliente X Buscar conversas dos últimos 7 dias em `dados/cliente-x/logs/`. Sintetizar nos 4 blocos: Entregas, Pendências, Riscos, Próximos passos. Renderizar via `templates/relatorio-pdf.html` com a cor amber. Salvar em `out/cliente-x/YYYY-WW.pdf`.
💡 Tip — vendor/sinapsis permite pin de versão
Quando Sinapsis lançar v4.6 (esperada Q3/2026), seu OS não quebra. O vendor/sinapsis
fica travado na v4.5 até você rodar bun run update-vendor
e validar em ambiente de staging. Isso é o que falta em 90% dos repos agênticos por aí —
atualização não pode ser surpresa em produção de cliente.
Userland. Por cliente.
Kernel. Do operador.
2 dirs distintos.
vendor/ trava versão.
💰 Custo real (sem maquiagem)
Marketing de stack agêntico costuma esconder o custo de setup. Aqui está o número honesto, baseado em onboardings reais da IA Masters Academy em 2026. Custo se divide em assinatura recorrente e tempo humano de setup.
📊 Custo médio observado em 2026
- US$ 100–200/mês — Claude Pro ou Max (dependendo do volume de tokens; Max compensa acima de ~3M tokens/mês).
- 4–8 horas — setup do primeiro cliente. Inclui CLAUDE.md, primeiras skills, validação de hooks, redact.
- ~1 hora — onboarding de cada cliente adicional, reusando 60–70% das skills.
- Payback em ~2 semanas — para operadores que já têm carteira de 5+ clientes ativos.
Tabela de payback por porte
| Operador | Clientes | Setup total | Payback |
|---|---|---|---|
| Freelance júnior | 3 | ~10h | ~3 semanas |
| Freelance sênior | 8 | ~15h | ~2 semanas |
| Agência boutique | 20 | ~28h | ~10 dias |
| Time consultoria | 30+ | ~40h | ~1 semana |
✓ Fazer
- ✓Copie skills da pasta
exemplos/tal-qual no primeiro cliente. - ✓Comece com 1 cliente real (não exemplo) no setup inicial.
- ✓Use Claude Pro nos primeiros 30 dias, suba pra Max quando tokens estourarem.
- ✓Calcule margem por cliente em planilha simples antes do próximo contrato.
✗ Evitar
- ✗Reinventar skills do zero quando o exemplo cobre 80% do caso.
- ✗Tentar atender 10 clientes na primeira semana. Comece em 1, valide em 30 dias.
- ✗Pular a etapa de redact — vaza dado de A pra prompt de B uma vez e perdeu a confiança.
- ✗Usar Claude Free em produção — context window pequeno demais pra multi-skill.
US$100–200/mês.
4–8h humanas.
~1h cada.
~2 semanas.
⚡ Instalação em 60 segundos
Desde a v0.6 existe um instalador único, bun run install-dream, que faz tudo: clone, configuração do Keychain, instalação do Sinapsis vendor, criação dos templates de launchd, e validação do primeiro health-check. Em macOS, leva ~60 segundos numa conexão decente.
Comandos exatos (copie e cole)
# 1. Pré-requisitos: Bun >= 1.1, Claude Code CLI, macOS 14+ brew install oven-sh/bun/bun brew install --cask claude # 2. Clone e entra git clone https://github.com/iamastersacademy/iamasters-os.git cd iamasters-os # 3. Instalação completa (Keychain + vendor + launchd) bun install bun run install-dream # 4. Valida bun run doctor # 5. Adiciona primeiro cliente bun run novo-cliente --nome="acme-corp"
O que o install-dream faz por baixo
Salva ANTHROPIC_API_KEY no Keychain
Via security add-generic-password. Nunca grava em .env em disco. Auditável via Keychain Access.app.
Copia Sinapsis v4.5 pra vendor/
Não é symlink, é cópia. Garante reprodutibilidade mesmo se o upstream sumir.
Registra launchd jobs
Indexação noturna do Sinapsis, backup diário das skills, rotação de logs por cliente.
Roda doctor + smoke test
Confere Keychain, perms, dscl, conectividade Anthropic, hash do vendor. Falha rápido se algo torto.
bun run install-dream
~60s no macOS.
Pode rodar 2x sem quebrar.
Validação automática.
🍎 Platform scope: macOS first
Decisão consciente, não preguiça. iAmasters OS depende de 3 primitivas nativas do macOS que não têm equivalente 1-pra-1 em Linux/Windows: Keychain (secrets), dscl (perfil do usuário), e launchd (jobs agendados). Em Linux, tudo roda — mas em modo degradado, com avisos.
🚨 Alerta — Linux roda degradado
Em distribuições Linux (testado em Ubuntu 22.04 e Fedora 40), o
auto-redact de dados sensíveis não funciona —
a feature usa dscl pra inferir o owner
da sessão e cruzar com a tabela de redação. Sem dscl, a engine cai em modo "log everything",
o que é inaceitável pra cliente regulado.
Mitigação: Em Linux, desligue o auto-redact e use redact manual via hook PreToolUse. Documentado em docs/linux-fallback.md.
Comparação cross-platform
| Feature | macOS 14+ | Linux | Windows |
|---|---|---|---|
| Install-dream | ✓ 60s | ⚠ degradado | ✗ via WSL |
| Secrets em Keychain | ✓ | ⚠ libsecret | ✗ |
| Auto-redact (dscl) | ✓ | ✗ | ✗ |
| Jobs agendados | ✓ launchd | ⚠ cron/systemd | ⚠ Task Scheduler |
| Skills/Sinapsis | ✓ | ✓ | ✓ |
💡 Por que macOS-first é defensável
Operadores de IA brasileiros em 2026 são ~85% macOS (dado de pesquisa interna IA Masters, n=412). Suportar 3 plataformas iguais triplicaria a superfície de bug e atrasaria features em 4–6 meses por ciclo. A decisão é: polir o caminho do usuário típico, oferecer fallback documentado para os outros.
Tier 1. Suportado.
Tier 2. Degradado.
Tier 3. Só via WSL.
Só macOS.
📝 Resumo do módulo
.claude/skills/ (userland) + Sinapsis engine em ~/.claude/vendor/sinapsis/ (kernel de memória).bun run install-dream resolve Keychain, vendor, launchd e doctor numa tacada.Próximo módulo:
4.2 — Estrutura de pastas do iAmasters OS (o mapa por baixo do capô)