MCP server + CLI pra controlar o NOS (Noclaf Operation System) a partir do Claude Code, Codex CLI e GitHub Copilot.

O que faz

Permite ao assistente de IA:

• Ler contexto do projeto (membros, sprint ativa, repositórios vinculados)
• Listar, criar, atualizar, mover entre colunas e comentar tarefas
• Bater ponto e cronometrar tempo em tarefas específicas

Instalação (mac / linux / windows)

Precisa apenas de Node.js 20+. Instala como pacote global:

npm i -g @noclaf/cli

Pronto. Os comandos noclaf (CLI) e noclaf-cli (servidor MCP) ficam disponíveis no PATH em qualquer SO.

Configurar em qualquer repo

Na raiz do repositório:

noclaf init

Esse único comando faz tudo:

1. Pede o seu PAT se você ainda não está autenticado (gera em https://nos.noclaf.com.br/profile#mcp).
2. Lista os projetos do NOS e você escolhe um (ou cola o UUID).
3. (Opcional) Escolhe o repositório vinculado.
4. Escreve noclaf.json na raiz e o adiciona ao .gitignore (binding local, não versionado).
5. Mostra o contexto carregado pra você validar.
6. Pergunta quais clientes MCP configurar — global ou por-repo.

Reinicie o cliente de IA depois pra carregar as tools.

Comandos do CLI

| Comando | Descrição | | ---------------------------------------------------- | -------------------------------------------------------- | | noclaf init | Faz tudo: autentica, vincula projeto, configura clientes | | noclaf login [pat] | Salva o PAT (interativo se omitido) | | noclaf logout | Apaga as credenciais | | noclaf whoami | Mostra o usuário autenticado | | noclaf skills status | Lista os docs do repo aberto de skills (via cache) | | noclaf sync | Atualiza o cache de skills e provisiona skills/commands/agents/hooks pros clientes configurados; checa atualização do CLI | | noclaf clean-legacy | Remove commands/skills legados (substituídos) de ~/.claude e ~/.codex (--dry-run, -y) | | noclaf --version | Imprime a versão |

Tools disponíveis

15 tools no MCP, divididas em quatro grupos.

Projeto

| Tool | O que faz | | ------------------- | ------------------------------------------------------------------------ | | nos_get_context | Snapshot do projeto ativo: nome, repos, sprint ativa, membros, você | | nos_list_projects | Lista os projetos que você acessa (marca o ativo) | | nos_set_project | Define o projeto ativo da sessão (só em memória, dura enquanto o servidor roda) |

Escopo do projeto. As tools de tarefa/alocação resolvem o projeto nesta ordem: argumento project_id da chamada → projeto ativo da sessão (nos_set_project) → default opcional de CLI de código (noclaf.json/NOCLAF_PROJECT_ID).

O projeto ativo é por sessão: vive só em memória, no processo do servidor MCP, e não é gravado em disco — ao reiniciar volta ao default. No Cowork, onde não há noclaf.json, é sempre assim que se escolhe o projeto: nos_list_projects → nos_set_project. (Como um processo do Claude Desktop pode ser compartilhado entre conversas, passe project_id direto na chamada quando quiser garantir o escopo de uma conversa específica.)

Tarefas

| Tool | O que faz | | ------------------ | ----------------------------------------------------------------------------- | | nos_list_tasks | Lista tarefas filtradas por status, assignee, sprint, prioridade, tipo, busca | | nos_get_task | Detalhes completos de uma tarefa | | nos_create_task | Cria nova tarefa (default: status=todo, sprint=active, assignee=você) | | nos_update_task | Atualiza campos de uma tarefa | | nos_move_task | Atalho pra mudar o status | | nos_comment_task | Adiciona comentário em uma tarefa |

Alocações (ponto + cronometragem)

| Tool | O que faz | | --------------------------- | ------------------------------------------------- | | nos_start_allocation | Bate o ponto | | nos_end_allocation | Encerra o ponto do dia | | nos_start_task_allocation | Começa a cronometrar uma task | | nos_end_task_allocation | Para de cronometrar a task atual | | nos_get_active_allocation | Estado atual: ponto, task ativa, segmentos do dia | | nos_list_my_allocations | Histórico de pontos |

Skills, commands e dependências

Além das tools, o noclaf entrega skills/commands/agents/hooks pros clientes. O conteúdo vive num repo aberto — Falcao-Tech/noclaf-skills — e não é um pacote npm. O CLI baixa o repo (zipball do GitHub, sem precisar de git) pra um cache local em ~/.noclaf/skills e lê de lá. noclaf sync atualiza o cache (pull da branch) toda vez, então as skills evoluem sem republicar o CLI; e auto-detecta quais clientes têm o noclaf configurado, provisionando pra cada um conforme a seleção de perfil/área do noclaf.json.

Overrides por ambiente:

| Variável | Efeito | | --------------------- | ------------------------------------------------------------------ | | NOCLAF_SKILLS_DIR | Aponta pra um checkout local do repo (dev) — vence tudo | | NOCLAF_SKILLS_REPO | Outro owner/repo (default Falcao-Tech/noclaf-skills) | | NOCLAF_SKILLS_REF | Outra branch/tag (default main) |

Cada cliente recebe no formato que entende:

| Cliente | Onde | Formato | | --------------- | ----------------------------- | ----------------------------------------------------------------------- | | Claude Code | ~/.claude/{commands,skills,agents} | arquivos nativos — slash-commands e skills | | Codex CLI | ~/.codex/ | dual-write: cada command/skill vira uma skill (skills/<id>/SKILL.md, auto-selecionada) e um custom prompt (prompts/<id>.md, no menu /prompts:<id>) | | Cowork/Desktop | — | via MCP prompts + resources, servidos ao vivo (ignora ~/.claude) |

Configurar o Codex grava NOCLAF_CLIENT=codex no config.toml, o que faz o servidor provisionar pra ~/.codex e filtrar os docs pelo surface codex. Reinicie o cliente depois do sync pra carregar skills/prompts novos.

Como aparecem no Cowork/Claude Desktop. Lá as skills chegam como prompts MCP, que o app expõe como slash-commands no menu de conectores/"+" (ex.: digite / e procure os itens do noclaf) — são invocados manualmente, não carregados sozinhos como Agent Skills que o modelo detecta e usa por conta própria. Se não aparecerem: feche o app de vez (Cmd+Q) e reabra, e confirme que o conector noclaf está conectado (deve listar as tools nos_*). O processo do Cowork lê o mesmo cache ~/.noclaf/skills — se o noclaf sync populou, o conteúdo está lá.

Visibilidade por cliente

Um doc pode ser restrito a clientes específicos via frontmatter:

clients: claude-code, cowork   # vazio/ausente = todos os clientes

Valores: claude-code, codex, cowork. O MCP filtra por esse campo, então um skill marcado cowork não é provisionado pro ~/.claude, e um claude-code não aparece como prompt no Cowork.

Dependências externas

Commands/skills podem depender de libs externas, declaradas como arquivos em dependencies/ no repo de skills (a presença do arquivo é a declaração). No fim do init/sync, a CLI lista cada uma e:

• instalador estruturado (npm:, skills: = npx skills add, git:) → oferece rodar com [y/N] (comando montado a partir do campo validado, sem shell);
• manual: (plugin de marketplace, passos no cliente, UI) → imprime os passos por cliente, com os comandos destacados. Ex.: o Ponytail é instalado por /plugin no Claude Code e codex plugin … + /hooks no Codex — a CLI não automatiza, só orienta.

A string install: (se houver) é só exibição — nunca é executada.

A CLI detecta o que já está instalado e mostra um selo verde ✓ instalada (sem repetir descrição/passos): npm via npm ls -g, git pelo dir de destino, skills por marcador/probe. Pra deps manual: (plugins), declare detect: no frontmatter com um ou mais globs — suporta ~, * e **, e segue symlinks (ok com dotfiles). Ex.: o Ponytail usa detect: ~/.claude/plugins/**/ponytail.

Checagem de cliente

Ao escolher um cliente no init, a CLI verifica se ele está de fato instalado na máquina. Se não estiver:

• CLIs (Claude Code, Codex) → mostra e oferece rodar o instalador: npm i -g @anthropic-ai/claude-code · npm i -g @openai/codex;
• apps (Claude Desktop/Cowork, VS Code) → mostra o link de download (ex.: https://claude.ai/download) — reabra o app depois de instalar.

Claude Desktop / Cowork

Selecione Cowork na lista de clientes do noclaf init (ou rode de novo). Com o app instalado e você já logado (noclaf login), a CLI ativa o conector direto — escreve o noclaf no claude_desktop_config.json usando caminhos absolutos (node + dist/mcp-server.js) e NOCLAF_CLIENT=cowork. Reinicie o Claude Desktop pra carregar. O noclaf sync reafirma esse config (atualiza os paths se o node/pacote mudou de lugar).

Não há projeto pra configurar: o Cowork não tem noclaf.json (sem working dir/repo), então o projeto é escolhido por sessão — peça pro assistente rodar nos_list_projects e depois nos_set_project com o id desejado.

Fallback: extensão .mcpb

Se o app estiver instalado mas a escrita direta falhar, ou você não tiver login salvo, a CLI cai pro fallback manual: gera uma extensão ~/Downloads/noclaf-cli-<versão>.mcpb e mostra os passos:

Configurações → Extensões → Configurações avançadas → seção "Extension Developer" → "Install Extension…" → selecione o .mcpb → preencha só o PAT.

Pela extensão a config não vem do noclaf login/noclaf.json, e sim do user_config, injetado como variável de ambiente:

| Variável | Origem (user_config) | Sensível | | ------------ | ---------------------- | -------- | | NOCLAF_PAT | PAT (noc_…) | ✅ sim |

Override de default (avançado, opcional). Fora do Cowork, em CLIs de código, você ainda pode definir NOCLAF_PROJECT_ID/NOCLAF_REPOSITORY_ID no env do cliente MCP pra fixar um projeto default — equivalente ao noclaf.json. O projeto da sessão (nos_set_project) e o project_id por chamada sempre têm precedência sobre esse default.

Atualizando

npm i -g @noclaf/cli@latest

O noclaf sync checa a versão publicada no início e, se houver uma mais nova, mostra um aviso e oferece atualizar ali mesmo (roda npm i -g @noclaf/cli@latest com sua confirmação; depois é só rodar o sync de novo). Use noclaf sync --yes pra aceitar sem prompt. A CLI também avisa em background em qualquer comando (via update-notifier).

Troubleshooting

• noclaf-cli: command not found — confirme o install global com npm i -g @noclaf/cli e que npm bin -g está no PATH.
• Tools não aparecem no Claude Code — reinicie o Claude Code depois do noclaf init. Confira com /mcp dentro dele.
• Não autenticado — rode noclaf init (que já faz login inline) ou noclaf login. No Cowork, confira se o PAT foi preenchido na extensão.
• Nenhum projeto selecionado — escolha o projeto da sessão: nos_list_projects → nos_set_project. (Em CLI de código você também pode rodar noclaf init pra criar um noclaf.json default no repo.)
• Skills não aparecem no Cowork — elas chegam como prompts MCP (slash-commands no menu de conectores/"+"), não como skills autônomas. Feche o Claude Desktop de vez (Cmd+Q) e reabra; confirme o conector conectado (tools nos_* listadas).
• Conteúdo de skills não encontrado — o cache ~/.noclaf/skills está vazio (fetch falhou / offline). Rode noclaf sync com rede, ou defina NOCLAF_SKILLS_DIR pra um checkout local. Confirme também que o repo de skills está público.
• ENOENT … mkdir ao provisionar (dotfiles) — um symlink em ~/.claude aponta pra um alvo inexistente. As versões atuais materializam o alvo automaticamente; se persistir, cheque o link.
• Sobraram comandos antigos (new-spec, apply-bug, init-sdd como command…) — rode noclaf clean-legacy (use --dry-run pra revisar antes) pra removê-los de ~/.claude e ~/.codex.

Convenções

• Idioma: UI/CLI em pt-BR. Código (variáveis, funções, tipos) em inglês.
• Backups: qualquer escrita em arquivo de config existente gera .bak.<timestamp> ao lado.
• stdout reservado pro JSON-RPC no MCP server — logs vão pra stderr.

Versão

v0.1.x — feature complete pra v1. Próximos passos: testes automatizados, suporte a múltiplos perfis de usuário.