MuxCode Docs

Introduction

O MuxCode é uma plataforma de IA composta por três peças que trabalham juntas:

• MuxCode Portal — interface de chat na web, com autenticação, histórico e acesso aos modelos disponíveis na sua conta.
• MuxCode CLI — agente de código no terminal: lê seu repositório, edita arquivos, roda comandos e abre PRs.
• Mux Gateway — interface unificada entre os clientes (Portal, CLI e editores) e os modelos disponíveis.

Comece pelo Install e em cinco minutos você terá um agente rodando no seu projeto.

Install

O Portal não precisa de instalação — acesse /portalmuxcode e crie sua conta. Para instalar a CLI, siga os 3 passos:

1 · Instalar

Linux / macOS

curl -fsSL https://muxcode.dnsdojo.com/install.sh | sh

Windows (PowerShell)

irm https://muxcode.dnsdojo.com/install.ps1 | iex

2 · Autenticar

Faça login com a sua conta do Portal:

muxcode login

3 · Rodar

No diretório do seu projeto:

cd meu-projeto
muxcode

Requisitos

• Nenhuma dependência externa — binário Rust único, sem Node/npm.
• Git 2.30+ (para workspaces e identidade agentic)
• Uma conta no MuxCode Portal

Desinstalar

# Linux / macOS
curl -fsSL https://muxcode.dnsdojo.com/uninstall.sh | sh
# Windows (PowerShell): irm https://muxcode.dnsdojo.com/uninstall.ps1 | iex

Remove o binário muxcode instalado e, se existir, uma instalação antiga via npm (@muxcodecli/cli, versão JS/Bun descontinuada).

Why Parallelize?

Um agente só consegue fazer uma coisa de cada vez — mas o seu backlog não. O MuxCode foi desenhado para rodar vários agentes em paralelo, cada um no seu próprio workspace isolado:

• Um agente corrige um bug enquanto outro escreve testes e um terceiro atualiza dependências.
• Cada agente trabalha numa cópia isolada do repositório (fork de workspace) — nenhum pisa no trabalho do outro.
• Você revisa os resultados e faz merge apenas do que prestou.

Paralelizar também viabiliza o padrão Best of N: lançar a mesma tarefa para N agentes e escolher a melhor solução.

Mux Gateway

O Gateway oferece uma API única e segura para usar os modelos MuxCode nas suas integrações:

Portal / CLI / Editores
        │
        ▼
   Mux Gateway ──► modelo MuxCode selecionado

• Seleção por modelo: cada requisição declara o produto MuxCode que deseja usar.
• Fila e prioridade: requisições interativas (chat) têm prioridade sobre jobs em lote.
• Uma credencial só: sua sessão do Portal vale para a CLI e integrações.

CLI

A CLI é o agente de código do MuxCode. Comandos principais:

Saiba mais na página MuxCode CLI.

Workspaces

Um workspace é o ambiente isolado em que um agente trabalha: uma cópia do seu repositório com estado próprio de arquivos, branch e histórico de conversa. O agente nunca edita seu checkout principal diretamente.

• Criado automaticamente quando você inicia uma sessão (muxcode).
• Listável com muxcode ws list; descartável com muxcode ws rm.
• O merge de volta para o seu branch é sempre uma ação explícita sua.

Forking Workspaces

Fork de workspace cria uma cópia de um workspace existente incluindo a conversa até aquele ponto. Use para explorar dois caminhos a partir do mesmo contexto:

# na sessão interativa
/fork experimentar-abordagem-b

O agente original continua intacto; o fork segue de forma independente. É a base do Best of N.

Sharing

Workspaces podem ser compartilhados com outros usuários da mesma organização MuxCode:

muxcode ws share <workspace> --with usuario@email.com

• O convidado vê a conversa e os diffs em modo leitura.
• Com --write, ele pode assumir a sessão (um piloto por vez).

.muxignore

O arquivo .muxignore (na raiz do projeto) lista caminhos que os agentes não podem ler nem enviar como contexto. Sintaxe igual ao .gitignore:

# segredos e credenciais
.env*
secrets/

# dados pesados que só poluem o contexto
dados/*.csv
*.sqlite

Diferença importante: .gitignore esconde do git; .muxignore esconde do modelo. Use os dois.

Agents

Um agente é uma sessão de modelo com ferramentas: ler/editar arquivos, executar comandos, buscar no repositório. O ciclo de vida:

1. Você descreve a tarefa.
2. O agente planeja (ou entra em Plan Mode, se exigido pela política).
3. Executa edições e comandos no workspace, pedindo permissão conforme o Policy File.
4. Apresenta o diff final para você revisar e mergear.

Instruction Files

Arquivos de instrução dão contexto permanente ao agente sobre o seu projeto. O MuxCode lê, nesta ordem:

Escreva neles o que você repetiria toda sessão: stack, comandos de build/teste, estilo de código, o que não tocar.

Agent Skills

Skills são procedimentos reutilizáveis que o agente pode invocar — um markdown com passos, scripts e exemplos, guardado em .muxcode/skills/<nome>/:

.muxcode/skills/
  release/
    SKILL.md      # como fazer release deste projeto
    bump.sh
  migracao-db/
    SKILL.md

Na sessão, invoque com /release ou deixe o agente escolher a skill adequada à tarefa.

Plan Mode

No Plan Mode o agente só lê — não edita nada nem roda comandos com efeito. Ele estuda o repositório e apresenta um plano; você aprova antes de qualquer mudança.

• Ative com /plan na sessão ou muxcode --plan.
• Recomendado para tarefas grandes, refactors e código que você não conhece.
• O Policy File pode exigir Plan Mode para certos caminhos.

System Prompt

O system prompt define a personalidade e as regras do agente. No MuxCode ele é composto por camadas:

1. Base do MuxCode — comportamento de engenharia, uso de ferramentas, segurança.
2. Instruction files — seu AGENTS.md e variantes.
3. Override do servidor — administradores podem fixar regras globais no Portal (Admin → Settings → System Prompt).

Prompting Tips

• Dê o critério de pronto: "refatore X mantendo os testes verdes" funciona melhor que "melhore X".
• Aponte arquivos: citar src/auth/login.ts poupa o agente de procurar às cegas.
• Uma tarefa por sessão: tarefas não relacionadas misturam contexto — paralelize em workspaces separados.
• Cole o erro inteiro: stack trace completo > descrição do erro.
• Peça plano primeiro em mudanças grandes (/plan).

Best of N

Para tarefas com várias soluções válidas, lance N agentes em paralelo na mesma tarefa e escolha o melhor resultado:

muxcode bestof 3 "otimize a query de relatórios mensais"

• Cria 3 workspaces independentes a partir do mesmo ponto.
• Cada agente resolve sem ver os outros.
• Você recebe os 3 diffs lado a lado para comparar e mergear o vencedor.

MCP Servers

O MuxCode fala MCP (Model Context Protocol) para plugar ferramentas externas — bancos, navegadores, APIs internas. Configure em .muxcode/mcp.json:

{
  "servers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": { "DATABASE_URL": "${secret:DB_URL}" }
    }
  }
}

As ferramentas do servidor MCP aparecem para o agente automaticamente. Segredos vêm de Project Secrets, nunca em texto puro.

Policy File

O .muxcode/policy.yaml define o que o agente pode fazer sem perguntar, o que exige confirmação e o que é proibido:

permissions:
  allow:
    - run: "npm test*"
    - run: "git status"
  ask:
    - run: "git push*"
    - edit: "infra/**"
  deny:
    - run: "rm -rf*"
    - read: ".env*"

A política do projeto (versionada no git) combina com a política do servidor definida pelo admin — vale sempre a mais restritiva.

Project Secrets

Segredos ficam no cofre do servidor, nunca no repositório nem no contexto do modelo:

muxcode secret set DB_URL "postgresql://..."
muxcode secret list

Referencie com ${secret:NOME} em configs (MCP, scripts de skill). O valor é injetado só no momento da execução do processo — o modelo vê apenas o placeholder.

Agentic Git Identity

Commits feitos por agentes são identificados como tais — auditáveis e separados dos seus:

git log --format="%an <%ae>"
# Peter <peter@email.com>            ← commit seu
# MuxCode Agent <agent@muxcode>      ← commit do agente

• Todo commit de agente inclui o trailer Co-Authored-By com o usuário que comandou a sessão.
• Em CI você pode tratar commits de agente com regras próprias (ex.: exigir review humano).

Keyboard Shortcuts

No Portal: ? abre a lista completa de atalhos do chat.

Notifications

Agentes longos avisam quando terminam ou quando precisam de você:

• Terminal: bell + título da janela quando a sessão pede confirmação.
• Portal: notificações web (ative no navegador na primeira visita).
• Webhook: configure notify.webhook no policy file para integrar com Slack/Discord.

Acessos MuxCode

Use os canais oficiais abaixo para acessar a plataforma:

Administradores gerenciam usuários e modelos no Portal em Admin Settings. Cadastros novos entram com papel user pendente de aprovação.

Vim Mode

Para quem vive no Vim, o input da CLI aceita modal editing:

# ative uma vez
muxcode config set editor.vim true

• Esc entra em normal mode; i/a voltam a inserir.
• Movimentos usuais: w b 0 $ dd ciw…
• No Portal, ative em Settings → Interface → Vim keybindings.

GitHub Actions

Rode o agente em CI para tarefas automatizáveis (triagem de issues, atualização de docs, correções sugeridas em PRs):

jobs:
  muxcode:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: curl -fsSL https://muxcode.dnsdojo.com/install.sh | sh
      - run: muxcode run "atualize o CHANGELOG com os commits desde a última tag"
        env:
          MUXCODE_TOKEN: ${{ secrets.MUXCODE_TOKEN }}
          MUXCODE_SERVER: https://muxcode.dnsdojo.com

Gere o token com muxcode token create --ci. Tokens de CI respeitam o policy file do projeto.

Symbol Shortcuts

Atalhos de símbolo aceleram referências no prompt:

VS Code Extension

A extensão coloca o agente dentro do editor: mesmo motor da CLI, com diffs inline.

1. Instale "MuxCode" no marketplace (ou code --install-extension muxcode.muxcode).
2. Conecte com sua conta do Portal (mesma sessão da CLI).
3. Cmd/Ctrl+Shift+M abre o painel do agente.

• Diffs aparecem como sugestões revisáveis arquivo a arquivo.
• A extensão respeita .muxignore e o policy file do projeto.

ACP (Editors)

O MuxCode implementa o Agent Client Protocol, o protocolo aberto que permite a qualquer editor compatível (Zed, Neovim via plugins, JetBrains) conversar com o agente:

# expõe o agente como servidor ACP
muxcode acp serve

Aponte o editor para o comando acima e ele ganha: sessões, edição de arquivos com aprovação, e streaming de respostas — sem extensão dedicada.

Debugging

• muxcode doctor — diagnóstico geral (rede, auth, git, versões).
• muxcode --verbose — loga cada chamada de ferramenta e requisição ao Gateway.
• Logs locais da CLI: ~/.muxcode/logs/.
• Se o Portal indicar indisponibilidade temporária, tente novamente e consulte o status do modelo.

Telemetry

O MuxCode usa apenas os dados operacionais necessários para entregar o serviço, acompanhar consumo e diagnosticar falhas. As definições disponíveis permitem controlar diagnósticos opcionais da CLI.

# desligar até as métricas locais
muxcode config set telemetry.local false

Storybook

Para desenvolvimento da UI do Portal: os componentes têm stories isoladas.

cd webui
npm run storybook   # http://localhost:6006

Use as stories para validar mudanças de tema (como o custom.css da marca) sem subir o app inteiro.

Terminal Benchmarking

A CLI mede a capacidade do terminal na primeira execução (cores, unicode, latência de render) e adapta a UI. Para re-rodar ou inspecionar:

muxcode bench terminal
muxcode bench terminal --json   # saída para scripts

Em terminais lentos (SSH com alta latência), a CLI reduz animações automaticamente — force com muxcode config set ui.simple true.

Context Boundaries for Compaction and Reset

Sessões longas estouram a janela de contexto do modelo. O MuxCode gerencia isso com dois mecanismos:

Compaction

Quando o contexto enche, a conversa antiga é resumida automaticamente e o resumo substitui as mensagens originais. O agente mantém o fio da meada, mas detalhes literais antigos podem se perder — fixe o que é crítico no AGENTS.md ou repita no prompt.

Reset

/reset zera a conversa mantendo o workspace (arquivos e branch intactos). Use quando a sessão "degringolou" e é mais barato recomeçar a conversa do que consertá-la.

CLI Goal Runs are not strict /goal aliases

muxcode goal "..." (CLI) e /goal (dentro da sessão) parecem iguais, mas não são:

Em scripts e CI, use sempre a forma CLI — o comportamento de permissões é determinístico.

AGENTS.md

O AGENTS.md na raiz do repositório é o contrato entre o seu projeto e qualquer agente. Estrutura recomendada:

# Projeto X

## Stack
Next.js 15 + Postgres (Prisma). Node 20.

## Comandos
- build: `npm run build`
- testes: `npm test` (precisa do Postgres local)

## Convenções
- Commits em português, imperativos.
- Nunca editar `src/generated/**`.

## Cuidado
- `infra/` é produção: só com aprovação.

• Vale para subdiretórios: um AGENTS.md em api/ complementa o da raiz.
• É lido por qualquer ferramenta compatível com a convenção — não só o MuxCode.