Para que serve o ClickUpfy
O ClickUpfy é a interface que o agente de código usa para ler uma tarefa do ClickUp, executar o trabalho no repositório e registrar o andamento no próprio ClickUp. O comando task get achata a tarefa, as subtarefas e os checklists numa fila execution com uma ação por item, por isso o agente fecha cada item pendente na ordem certa e o plano, os comentários, o tempo e o status ficam no workspace onde você acompanha o projeto.
Ficha e sumário da página
- Referência técnica
- ClickUpfy v1.1.2
- Revisão
- 13 de novembro de 2026
- Conteúdo
- Documentação oficial consultada
O trabalho continua no ClickUp
Uma tarefa no ClickUp guarda a descrição, as subtarefas, os checklists, os comentários, o status e o tempo registrado. Sem uma camada entre o agente e o workspace, cada agente de código precisa descobrir como autenticar na API, quais endpoints chamar, em qual List trabalhar e como representar uma tarefa com subtarefas aninhadas. O ClickUpfy concentra essas respostas em três peças: o perfil local associa uma API key a um workspace, o projeto fixa o perfil e a List nos arquivos do cliente MCP e as skills descrevem a ordem do trabalho.
Com isso, você continua acompanhando o projeto na interface do ClickUp enquanto o agente escreve no mesmo lugar. O plano aparece como comentário na tarefa, os itens de checklist são marcados conforme os testes passam e o cronômetro registra o tempo no seu usuário. O ClickUpfy não guarda cópia local das tarefas, então a próxima leitura parte do estado remoto.
A tarefa como fila executável
A resposta de task get traz a tarefa original e uma propriedade chamada execution. Essa propriedade transforma a árvore da tarefa numa fila ordenada, com a tarefa principal, as subtarefas de qualquer nível e os itens de checklist. Cada item recebe uma chave estável para a leitura atual, como task:86abc123 para uma tarefa ou checklist:check-1:item-1 para um item de checklist.
Cada item da fila informa o tipo, a chave do pai em parentKey, a profundidade em depth, o estado aberto ou concluído e o campo action, com o comando da CLI e a chamada MCP que concluem aquele item. O agente escolhe um item pendente, executa o trabalho e usa a ação indicada, sem tratar uma subtarefa aninhada como trabalho solto. A fila descreve só a leitura atual, por isso o agente lê a tarefa de novo depois de qualquer alteração.
Quando o agente precisa ler a tarefa como documento, o modo --markdown devolve metadados, descrição, resumo e checkboxes hierárquicos num texto único. No servidor MCP, a mesma leitura sai pela ferramenta clickupfy_task_get com markdown: true, sem a string JSON escapada, o que reduz o ruído no contexto do agente.
O ciclo de uma tarefa executada pelo agente
A skill clickup-issue-implement descreve o caminho de uma tarefa do ClickUp da leitura à conclusão. O diagrama abaixo segue esse caminho com as ferramentas reais do servidor MCP, na versão de referência.
Ler a tarefa
clickupfy_task_getA tarefa chega inteira, com subtarefas, checklists e a fila execution.
Publicar o plano
clickupfy_comment_createO plano visível fica como comentário na própria tarefa.
Medir o tempo
clickupfy_time_startO cronômetro começa quando a implementação começa, depois de conferir o atual.
Fechar os itens
clickupfy_checklist_item_setUm item de teste só fecha depois que o comando correspondente passa.
Concluir
clickupfy_task_updateO status final é um status terminal que existe na List do projeto.
Cada etapa do ciclo depende de uma condição que a skill confere. O tempo só começa quando a implementação começa: a documentação do registro de tempo recomenda não registrar automaticamente leitura inicial, esclarecimento e espera por autorização. Antes de iniciar, a skill consulta clickupfy_time_current, porque o ClickUp mantém um cronômetro por usuário e um novo início em outra tarefa troca o cronômetro e devolve a tarefa anterior no campo previous.
A conclusão exige três conferências: a releitura do estado remoto, a regressão aplicável ao projeto e um status terminal que exista na List. O ClickUpfy não decide qual status representa conclusão, porque cada List do ClickUp pode ter nomes diferentes. Por isso a skill lê os status com clickupfy_list_get e escolhe um deles, sem inventar grafia.
Criar tarefa e executar tarefa são trabalhos separados
O ClickUpfy separa a criação da execução. A skill clickup-issue-create transforma uma solicitação numa tarefa com descrição em Markdown, subtarefas e checklists de teste, sem editar código e sem marcar validações como concluídas. A execução fica com clickup-issue-implement. As consultas pontuais do dia a dia ficam com clickupfy-dev, que lê uma tarefa, publica o resultado de um teste ou marca um checklist específico sem transformar a consulta numa implementação completa.
Sem o ClickUpfy
- Cada agente monta a própria chamada à API do ClickUp, com a chave colada no ambiente do projeto.
- A tarefa chega como JSON aninhado, com a ordem das subtarefas decidida pelo agente.
- O andamento fica no terminal e some quando a sessão termina.
- O status final depende de uma grafia escrita pelo agente.
Com o ClickUpfy
- O agente chama ferramentas com schema, enquanto a API key fica no cofre do perfil local.
- A fila
executiontraz cada item pendente com a ação que o conclui. - Plano, checkpoints e tempo ficam registrados na tarefa, visíveis no ClickUp.
- O status final sai da lista de status que a List do projeto declara.
Onde o ClickUpfy se encaixa
Com o trabalho já organizado no ClickUp, você dá aos agentes de código acesso às mesmas tarefas que acompanha na interface. A CLI também funciona sem agente nenhum: a saída em JSON e os exit codes estáveis encaixam o binário em scripts e automações, como mostra a página Comandos e recursos.
Para um repositório trabalhar só numa List, o servidor MCP de cada projeto recusa IDs diferentes dos que foram fixados, assunto da página O servidor MCP por projeto. O percurso de instalação e configuração completo, com cada parâmetro, está na documentação do ClickUpfy. O fluxo de leitura e alteração de tarefas tem página própria em Tarefas e checklists.