Primeiros passos

Encontre respostas
no seu projeto

O Atlas ajuda o assistente do seu editor a encontrar código e documentos. Siga estes quatro passos para fazer sua primeira pergunta e descobrir quais arquivos consultar.

Prepare o computador

Abra a pasta do projeto que você quer consultar no editor que já usa: Cursor, VS Code com Copilot, Claude Code, Kiro ou OpenCode. Você não precisa baixar uma cópia do repositório do Atlas.

Abra o terminal do editor — a área em que você digita comandos. No Windows, use o PowerShell. Cole cada linha abaixo e pressione Enter:

No terminal — conferir as ferramentas

uv --version
git --version

Deu certo? Cada comando mostra um número de versão. O uv prepara o Atlas e suas dependências; o Git permite baixar o pacote do GitHub.

Algum comando não foi encontrado?

Instale a ferramenta que faltou: instalação oficial do uv ou instalação oficial do Git. Escolha seu sistema operacional. Depois, feche e abra novamente o editor e repita a conferência.

Prepare uma versão de Python compatível com o Atlas. Este comando instala o Python 3.12, ou confirma que ele já está disponível:

No terminal — preparar o Python

uv python install 3.12

Internet na primeira preparação. O Atlas baixa o pacote, as dependências e o modelo usado na busca. Depois desses downloads, a indexação e a busca rodam localmente na configuração padrão deste guia. O chat do seu editor pode continuar dependendo de internet.

Prepare a busca no seu projeto

O Atlas precisa criar um índice: um catálogo dos arquivos para encontrar trechos relevantes. Faça isso uma vez para cada projeto.

No terminal, entre na pasta principal do seu projeto. Substitua o caminho do exemplo pelo caminho real e mantenha as aspas se houver espaços:

Como entrar na pasta do projeto

macOS ou Linux — exemplo de caminho

cd "/Users/ana/Projetos/minha-loja"

Windows (PowerShell) — exemplo de caminho

cd "C:\Users\Ana\Projetos\minha-loja"

Para conferir a pasta atual, use pwd no macOS/Linux ou Get-Location no PowerShell.

Cole este comando inteiro, em uma única linha:

No terminal — criar o índice

uvx --from git+https://github.com/LuisCarlosLopes/codesteer-atlas.git atlas-index --workspace .

O ponto final significa “a pasta em que o terminal está agora”. Confira o caminho mostrado em Workspace:. Aguarde o término; o primeiro uso pode levar mais tempo por causa dos downloads.

Deu certo? Aparece Indexação Concluída com Sucesso!, com um total de trechos (chunks) maior que zero. A pasta .code-index é criada dentro do seu projeto. Ela pode ficar oculta na lista de arquivos.

Se o projeto usa Git, adicione .code-index/ em uma nova linha do arquivo .gitignore na pasta principal. Isso mantém o índice gerado fora do histórico do projeto.

Conecte o Atlas ao seu editor

A conexão usa MCP, o meio pelo qual o assistente acessa ferramentas como o Atlas. Configure apenas o editor que você usa, dentro do projeto aberto.

Abra sua opção abaixo, crie o arquivo indicado e copie o conteúdo. Os nomes que começam com ponto fazem parte do caminho. Salve o arquivo.

O arquivo já existe? Acrescente só a entrada codesteer-atlas à seção indicada no exemplo, mantendo as outras ferramentas. Se precisar, peça ao assistente: “Adicione esta configuração do Atlas ao arquivo existente, preservando as outras entradas”.

Cursor

Crie .cursor/mcp.json dentro da pasta principal do seu projeto. Crie também as pastas do caminho, se necessário.

.cursor/mcp.json — conteúdo do arquivo

{
  "mcpServers": {
    "codesteer-atlas": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/LuisCarlosLopes/codesteer-atlas.git",
        "atlas-serve"
      ],
      "env": {
        "ATLAS_INDEX_DIR": "${workspaceFolder}/.code-index"
      }
    }
  }
}

VS Code com GitHub Copilot

Crie .vscode/mcp.json dentro da pasta principal do seu projeto. Crie também as pastas do caminho, se necessário.

.vscode/mcp.json — conteúdo do arquivo

{
  "servers": {
    "codesteer-atlas": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/LuisCarlosLopes/codesteer-atlas.git",
        "atlas-serve"
      ]
    }
  }
}

Claude Code

Crie .mcp.json dentro da pasta principal do seu projeto. Crie também as pastas do caminho, se necessário.

.mcp.json — conteúdo do arquivo

{
  "mcpServers": {
    "codesteer-atlas": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/LuisCarlosLopes/codesteer-atlas.git",
        "atlas-serve"
      ]
    }
  }
}

Kiro

Crie .kiro/settings/mcp.json dentro da pasta principal do seu projeto. Crie também as pastas do caminho, se necessário.

.kiro/settings/mcp.json — conteúdo do arquivo

{
  "mcpServers": {
    "codesteer-atlas": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/LuisCarlosLopes/codesteer-atlas.git",
        "atlas-serve"
      ],
      "autoApprove": [
        "atlas_brief",
        "atlas_search",
        "atlas_graph",
        "atlas_context",
        "atlas_status"
      ]
    }
  }
}

OpenCode

Crie opencode.json dentro da pasta principal do seu projeto. Crie também as pastas do caminho, se necessário.

opencode.json — conteúdo do arquivo

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "codesteer-atlas": {
      "type": "local",
      "command": [
        "uvx",
        "--from",
        "git+https://github.com/LuisCarlosLopes/codesteer-atlas.git",
        "atlas-serve"
      ],
      "enabled": true
    }
  }
}

Feche e abra novamente o editor no mesmo projeto. Na área de ferramentas ou servidores MCP, confira se codesteer-atlas aparece conectado. Se o editor pedir para habilitar a conexão, habilite-a.

Deu certo? O assistente tem acesso a ferramentas como atlas_brief e atlas_search. O editor inicia o Atlas para você.

Faça sua primeira pergunta

Abra o chat do editor em um modo que permita usar ferramentas e envie:

No chat — conhecer o projeto

Use atlas_brief para explicar este projeto em linguagem simples e indicar os principais arquivos por onde posso começar.

Depois, peça uma busca concreta. Troque “login” por um assunto que exista no seu projeto, como “pagamento” ou “configuração”:

No chat — encontrar uma funcionalidade

Use atlas_search para encontrar onde o login é tratado. Leia os trechos relevantes e me explique o que acontece, citando os arquivos e as linhas.

Seu primeiro resultado útil: o chat mostra uma chamada ao Atlas e uma resposta com caminhos de arquivos e linhas que você consegue abrir. Você já pode usar esses trechos para entender o projeto ou orientar uma mudança.

Se vierem só nomes de arquivos, peça: “Leia os trechos desses resultados e explique”. O Atlas primeiro localiza os trechos; o assistente usa esse conteúdo para responder.

Quando os arquivos mudarem

Repita o comando do passo 2, na mesma pasta. Ele atualiza o índice aproveitando os arquivos que não mudaram. Você também pode pedir no chat: “Use atlas_index para atualizar o índice deste projeto”.

Preciso de ajuda

O terminal reconhece uvx, mas o editor não encontra o comando

Feche completamente o editor e abra-o novamente. Se persistir, use command -v uvx no macOS/Linux ou (Get-Command uvx).Source no PowerShell. Troque "uvx" no arquivo de configuração pelo caminho retornado. Em JSON no Windows, use barras duplas, como C:\Users\Ana escrito como C:\\Users\\Ana.

Apareceu “Índice local não encontrado”

Conclua o passo 2 na pasta do projeto e reabra o editor nessa mesma pasta. Se continuar, peça no chat: “Use atlas_status e me mostre index_path e index_resolution”. O caminho deve apontar para a pasta .code-index do seu projeto.

Se apontar para outro lugar, consulte como indicar o caminho do índice abaixo.

O assistente diz que não tem atlas_search

Confira o nome e a localização do arquivo do passo 3. Verifique se o Atlas está habilitado nas conexões MCP e reabra o editor. Use um modo de chat com acesso a ferramentas.

O download falhou no primeiro uso

Confira a conexão e tente novamente o comando do passo 2. Os downloads incluem o GitHub e o modelo de busca do Hugging Face. Se a rede da empresa bloquear um deles, encaminhe a mensagem de erro ao suporte da sua equipe.

A busca veio vazia ou o total de trechos é zero

Confira se a pasta indexada contém código ou documentos, como arquivos Python, JavaScript ou Markdown. Tente buscar um nome que aparece em um arquivo. Arquivos excluídos por .atlasignore, pastas como node_modules e arquivos maiores que 2 MB não entram na busca. Veja os formatos de documentos e atualize o índice após corrigir a pasta.

Apareceu “Indexação Concluída COM FALHAS”

Alguns arquivos ficaram fora do índice. Veja os avisos anteriores à mensagem final, corrija o problema indicado e repita o passo 2. Se precisar de ajuda, copie a mensagem de erro e o nome do arquivo afetado para sua equipe.

Para depois, se precisar

Ativar o Jev com entrega compacta (opcional)

O guia funciona com a busca local. Para usar o Jev, você precisa de uma chave do OpenRouter e aceita enviar a consulta e os trechos candidatos para essa API, com custo de uso.

Na configuração MCP do editor, mescle estas propriedades no env existente da entrada do Atlas. Preserve o caminho do índice e as outras propriedades. No OpenCode, o campo equivalente se chama environment.

Propriedades opcionais — substitua a chave de exemplo

"ATLAS_RELEVANCE": "1",
"ATLAS_RELEVANCE_API_URL": "https://openrouter.ai/api/v1/systemone",
"ATLAS_RELEVANCE_API_KEY": "sua-chave-openrouter",
"ATLAS_CONTEXT_OPTIMIZATION": "1"

Reinicie o MCP ou reabra o editor. Peça ao assistente para consultar atlas_status e conferir relevance.enabled, relevance.rubric, relevance.cut e relevance.egress. O status declara a configuração; não testa a conexão com a API.

A rubrica v2 já é o padrão. No perfil compacto, o Jev corta avaliações abaixo de 1,5 na escala de 0 a 3, sem repor as vagas; a resposta pode ter menos itens que top_k. Correspondências exatas e candidatos sem avaliação permanecem. As flags do Jev e do perfil compacto são independentes.

Guarde a chave em configuração local, fora do Git. Para desligar o Jev, remova ATLAS_RELEVANCE ou mude para 0 e reinicie o MCP. Veja rubrica, corte, limites e fallback.

Indicar o caminho do índice manualmente

Para Cursor, VS Code, Claude Code e Kiro, adicione env dentro da entrada codesteer-atlas, ao lado de command e args. Se já existir env, ajuste apenas ATLAS_INDEX_DIR. Use o caminho completo da pasta .code-index criada no passo 2.

Trecho para acrescentar à configuração — ajuste o caminho

"env": {
  "ATLAS_INDEX_DIR": "/Users/ana/Projetos/minha-loja/.code-index"
}

Separe as propriedades com vírgula. No Windows, use barras normais no caminho, por exemplo C:/Users/Ana/Projetos/minha-loja/.code-index. Reabra o editor depois de salvar.

No OpenCode, acrescente "--index-dir" e o caminho completo ao final da lista command, depois de "atlas-serve".

Ver as conexões do projeto: abra o arquivo .code-index/graph.html no navegador, após indexar.
Conhecer as ferramentas do Atlas.
Jev e entrega compacta (opt-in: modelo System One da TypeSafe, chamado via OpenRouter).
Orientar o assistente a usar o Atlas nas próximas conversas.
Configuração avançada e contribuição.

Encontre respostas no seu projeto