Setup de geração de imagem e vídeo, multi-provider (Fal, Google Gemini, Higgsfield), operado conversacionalmente via Claude Code.
O estado é global e único por máquina: mora em ~/.studiolocal/, e a pasta em que você abre o terminal não decide nada sobre ele. O que ainda depende da pasta é a credencial, que funciona standalone (.env do root global) ou embedded em workspaces refinados (metaKosmos, Ktirio, Montuvia, 214, David-OS), herdando a chave do .envmk/.env de lá.
- macOS ou Linux
- Python 3.11+ (
python3 --version) - git, para clonar e atualizar. Sem git também dá: ver abaixo
- Claude Code instalado e rodando
- Chave de pelo menos um provider: Google Gemini (aistudio.google.com/apikey), Fal.ai (fal.ai/dashboard/keys) ou Higgsfield (cloud.higgsfield.ai/api-keys)
O repo é público, então o clone é anônimo por HTTPS: não precisa de gh autenticado, de conta na org nem de chave SSH. Clone onde você quiser e rode o script de dentro do clone.
git clone https://github.com/metaKosmos/studiolocal.git
bash studiolocal/scripts/install.shIsso instala o pacote Python em modo editável (pip install -e .), registra o CLI studiolocal e instala 14 skills em ~/.claude/skills/: as 13 /studio-* mais a /studiolocal-install.
Onde a fonte (o código) fica, na ordem de precedência:
| # | Caminho | Quando |
|---|---|---|
| 1 | $STUDIOLOCAL_REPO |
override explícito, ganha de tudo |
| 2 | o clone de onde você rodou o script | sempre que rodar de dentro de um clone |
| 3 | ~/Desktop/David-OS/modules/studiolocal |
só se já existir aí: era o default antigo, e continua valendo para quem está instalado nele |
| 4 | ${XDG_DATA_HOME:-~/.local/share}/mk-ai-studio/studiolocal |
default em máquina nova |
O default era o caminho 3, que é o vault pessoal de uma pessoa. Numa máquina qualquer ele criava uma pasta ~/Desktop/David-OS/ sem significado para quem a recebia, e chegou a produzir duas pastas de fonte quase idênticas na mesma máquina. O instalador nunca cria a segunda: se acha a fonte legada, usa e avisa.
No Windows a fonte canônica é %LOCALAPPDATA%\mK AI Studio\studiolocal, e quem instala lá é o pacote do Workbench, não este script (que é bash).
Sem git na máquina: baixe o zip de main, extraia na pasta da tabela acima e rode bash <fonte>/scripts/install.sh. Daí em diante studiolocal update atualiza sem git.
Se você é do time do AI Studio, não faça nada disso. Use o pacote do Workbench, que já traz o StudioLocal embutido e não pede git nem conta no GitHub.
studiolocal installNo Claude Code, /studiolocal-install faz o mesmo e explica cada passo.
O comando cria ~/.studiolocal/ com tracker.db, as pastas (projects/, workflows/, _tmp/, archive/, logs/), o .env e o config.yaml, e aplica as migrations. Ele não toca no CLAUDE.md da pasta em que você está, a não ser que você peça com --claude-md <dir>.
Depois disso, rodar qualquer comando de qualquer pasta é o normal e o correto, e não cria nada ali. Migration pendente é aplicada sozinha no primeiro comando seguinte, com backup do banco antes.
Se você já usava o StudioLocal quando cada pasta tinha o seu .studiolocal/, o install adota a instalação antiga quando acha uma só. Com duas ou mais ele para e pede studiolocal db adopt --primary <caminho>, porque escolher sozinho seria decidir em qual banco fica o histórico de custo dos outros.
Para apontar o estado a outro lugar: a flag --root, ou as variáveis STUDIOLOCAL_ROOT e STUDIO_DATA_ROOT (esta última é compatibilidade com o Workbench: aponta para o diretório pai do .studiolocal/ e só aproveita instalação que já existe, nunca cria). studiolocal root diz qual root está em uso e de onde veio a decisão.
bash scripts/doctor.sh # de dentro da fonte; de fora: bash <fonte>/scripts/doctor.shReporta CLI, a fonte em uso (o diretório do pyproject.toml de onde o pacote foi importado, não um caminho fixo), skills, idade da calibração do models.yaml, o data root em uso com a origem da decisão, e quais credenciais de provider existem nesta máquina. Credencial de provider ausente é aviso e não erro: a máquina que gera por Gemini nunca teve FAL_KEY.
Achando mais de uma fonte plausível na máquina, ele avisa e diz qual o CLI executa. Duas fontes é o sintoma da instalação duplicada, em que a pessoa edita uma pasta e o CLI roda a outra.
Para conferir que a instalação funciona numa máquina que não é esta:
bash scripts/test-install-limpo.shRoda o fluxo inteiro com HOME num diretório temporário, sem tocar no HOME real, e imprime no fim o que provou e o que não conseguiu provar (o clone vem de um repo local, não do GitHub; as dependências do pip vêm desta máquina; Windows e Linux não são exercitados).
O catálogo vive em models.yaml e cobre três providers: fal, gemini (API Google direta) e higgsfield (Cloud API e CLI por créditos do plano). Quem lista o catálogo desta instalação, com params, notas e quais têm credencial aqui, é o CLI:
studiolocal models # ok = credencial presente; -- = a chamada falharia
studiolocal models --kind imageDefaults, usados quando você não passa --model: nano-banana-pro-google (imagem), seedance-2-cli (vídeo), clarity (upscale).
7 entidades. Detalhes em docs/DESIGN.md.
- Project: container de trabalho criativo, com uma empresa dona (
--org) - Brief: documento de intenção (opcional)
- Session: período contínuo de trabalho (auto-gerenciado)
- Workflow: receita YAML reutilizável (criada a posteriori)
- Run: execução nomeada de um Workflow
- Generation: 1 chamada de API do provider, 1 ou mais outputs
- Asset: output individual (status draft / library / discarded)
/studio-project, /studio-image, /studio-video, /studio-upscale, /studio-promote, /studio-discard, /studio-workflow, /studio-run, /studio-cleanup, /studio-report, /studio-status.
Abertura e fechamento de frente, gravados no ESTADO.md do project:
/studio-start: lê oESTADO.mde diz onde você parou, o que já ficou decidido e qual o próximo passo./studio-end: grava onde você parou, o que ficou decidido, o próximo passo e o que não funcionou, e roda o cleanup seguro.
No Claude Code, de qualquer pasta:
você: novo project Hero Fashion Q2, tag campaign:q2
Claude: ✓ Project hero-fashion-q2 criado.
você: gera 4 imagens de modelo feminina vestindo terno bege oversized,
fundo concreto cinza, luz lateral hard, 3:4
Claude: nano-banana-pro-google × 4, R$ 2,72 estimado. Confirma?
você: vai
Claude: ✓ 4 imagens em ~/.studiolocal/projects/hero-fashion-q2/drafts/...
você: a 03 ficou. upscale 4x e depois anima orbit 5s
Claude: [executa em sequência, com o custo real de cada passo]
você: salva esse processo como workflow Hero Fashion Light
Claude: ✓ workflows/hero-fashion-light.yaml. Use `/studio-run` pra reusar.
você: quanto gastei esse mês com campaign:q2?
Claude: [tabela markdown com total, por modelo, por project]
studiolocal root # qual data root está em uso, e por quê
studiolocal update # atualiza a fonte em uso + migrations
studiolocal status # estado geral
studiolocal project list # projects ativos
studiolocal report --month 2026-05 # custos do mês
studiolocal report --org metakosmos # custos de uma empresa só
studiolocal cleanup # revisão manual
studiolocal cleanup --safe # auto end-session
bash scripts/doctor.sh # diagnósticoCom mais de uma empresa no recorte, o report não imprime total consolidado: sai um resumo por org. Somar empresas distintas num número só produz um valor que não serve a nenhuma delas. Para consolidar de propósito, --all-orgs.
Apps do Workbench (Crystal Ball e outros manifestos de templates/apps/):
studiolocal workflow install # registra todo o catálogo de apps no root
studiolocal workflow install crystal-ball --force # reinstala um, sobrescrevendo edição manual
studiolocal run crystal-ball --project p --stream-json # narra a run em NDJSON, evento a evento
studiolocal runs show 42 --json # registro completo de uma run, com o contrato da pausa
studiolocal runs cancel 42 --motivo "abandonada" # encerra run que ninguém vai responder
studiolocal runs reap # fecha generation pendurada por processo morto
studiolocal refine 42 --alvo prompt_video --queixa "o gancho está fraco" # ajusta fora do pipelineworkflow install roda sozinho no fim de studiolocal install, sem --force: uma máquina nova já nasce com o catálogo, e um YAML editado à mão no root nunca é sobrescrito em silêncio. refine nunca toca status/finished_at da run — só marca a nota como desatualizada.
--stream-json é como se acompanha uma run longa: uma linha NDJSON por evento, com o run_id já na primeira (antes, ele só saía no fim, e um crash de quem disparou perdia o ponteiro) e sempre um evento terminal — done, paused ou failed. Não se combina com --json, que segue imprimindo uma linha só, no fim.
runs cancel é a saída de uma run abandonada: canceled, generations abertas fechadas e o pedido de decisão humana apagado da sessão, numa transação só. Recusa run done.
runs reap fecha a generation que um processo morto deixou pending e que prenderia o card em "em geração". A mesma varredura roda sozinha no início de cada run.
- docs/DESIGN.md: plano de arquitetura V1 completo
models.yaml: catálogo de modelosmigrations/: schema SQLite versionadotemplates/: templates de Brief, Workflow, Project README
Privada (David Benalcázar Chang). A definir antes de eventual open-source.