DEV Community: Gabriel Menezes

One MCP config for Claude Code, OpenCode and OMP

Gabriel Menezes — Thu, 15 Oct 2026 03:29:23 +0000

Three files for one server

You use Claude Code for one task and OpenCode for another, and both should see the same Figma and Linear MCP servers. Each harness wants them in its own file, under its own keys:

harness	file
Claude Code	`.mcp.json`
OpenCode	`opencode.json`
OMP	`.omp/mcp.json`

Writing three files once is tedious. Keeping them equal is the real cost: change a URL in one, forget the others, and half your sessions start without the server. Then each harness needs its own login.

Where the login breaks

The files are the easy part. Authentication fails differently in each harness:

server	harness	the harness's own login	what `ivar mcp auth` does
Figma	OpenCode	Figma refuses OpenCode's client registration; `opencode mcp auth` prints `Authentication failed` and exits 0	registers a client under a name Figma accepts, runs the browser flow and writes the tokens into OpenCode's store
Figma, Linear	OMP	OMP has no MCP login command	runs the browser flow itself and imports the token with `omp auth-broker import`
Figma, Linear	Claude Code	`claude mcp login` works	hands the browser step to `claude mcp login`
Linear	OpenCode	`opencode mcp auth` works	hands the browser step to `opencode mcp auth`

Where the harness's own login works, ivar uses it. It only takes over where the harness cannot finish. Figma MCP on OpenCode: fix "Authentication failed" explains the Figma case in detail.

Declare once

Install ivar, create a hall in an empty directory with the harnesses you use, and add the servers:

curl -fsSL 'https://ivar.run/install?ref=one-mcp-config' | sh
mkdir tools-hall && cd tools-hall
ivar init --provider claude-code
ivar provider add opencode
ivar provider add omp
ivar mcp add figma
ivar mcp add linear

figma and linear are known names, so ivar mcp add fills in their URLs. Any other HTTP server takes --url, for example ivar mcp add sentry --url https://mcp.sentry.dev/mcp. Adding a server that is already declared the same way changes nothing; adding one with the same name and a different URL is refused instead of overwriting it.

The declaration lives in the hall's ivar.json:

{
  "mcp": [
    { "name": "figma", "type": "http", "url": "https://mcp.figma.com/mcp" },
    { "name": "linear", "type": "http", "url": "https://mcp.linear.app/mcp" }
  ]
}

ivar mcp add writes each harness's file from it on the spot. After you edit ivar.json by hand, ivar sync rewrites the three files to match.

Authenticate once per server

ivar mcp auth figma --all-providers
ivar mcp auth linear --all-providers
ivar mcp status

--all-providers runs every harness the hall lists, one after the other, because each login takes over the terminal and waits on the browser. Every harness is attempted even if an earlier one fails, and the run is reported as needing attention when any of them does. When a client registration happens first, as with Figma on OpenCode, it is reported apart from the login: a registered client is not yet an authenticated one.

ivar mcp status prints which server has credentials on which harness. The client secret lives in .ivar/secrets/mcp.env, outside git. Tokens never go into ivar.json, so you can commit the file and a teammate gets the same servers after their own ivar mcp auth.

Do you need this?

With one harness and a server whose login works there, no. Add the server to that harness's file and run its login. ivar earns its place when you use more than one harness, when a team should share the same servers, or when the login fails, as it does for Figma on OpenCode and for any OAuth server on OMP.

Limits

Three harnesses: Claude Code, OpenCode and OMP.
macOS and Linux. Windows is not supported, and WSL is untested.
HTTP MCP servers. Figma and Linear are the servers ivar mcp auth has been run against. For another OAuth server, Claude Code and OpenCode use their own login and OMP uses the flow ivar runs; whether that server accepts it is up to the server.
The OAuth flow talks to each MCP server directly. ivar has no server of its own in the middle.

Then add your repos

The hall that holds your MCP servers is also where ivar mounts your repositories and runs a feature across them, with every session reading the same servers. The quickstart mounts the first repo. The MCP guide covers transports and OAuth per harness.

Figma MCP on OpenCode: fix "Authentication failed": why Figma refuses OpenCode's registration and the four commands that fix it.
Declare MCP servers once for every harness: the short recipe.
Harness pages: Claude Code, OpenCode, OMP.

One repo, many agents: parallel features from a Figma prototype

Gabriel Menezes — Wed, 30 Sep 2026 00:56:35 +0000

One repo, one big prototype

Your designer hands over a Figma prototype with onboarding, checkout and a profile area. It all lands in one app repository. You want three agents working at once, one per area, and you want the result to arrive as a single pull request.

Does ivar make sense with one repo and many parallel branches, or only when work spans several repositories? It does, and this post walks through it end to end.

The hall with one repo

Create the hall as its own git repo, then add the app repository:

mkdir app-hall && cd app-hall && git init
ivar init
ivar repo add app git@github.com:acme/app.git

ivar init sets the hall up for Claude Code. For OpenCode or OMP, run
ivar init --provider opencode or ivar init --provider omp instead.

The Figma MCP server is declared once in ivar.json and materialised into each session, so every agent you start can read the prototype. Configure Figma MCP for OpenCode in one step shows the block and the auth step, and the MCP guide covers the other harnesses.

A fresh worktree is a clean checkout. Installed dependencies and generated code are not there. Put what a new worktree needs in a setup script at .ivar/setups/app.sh:

set -euo pipefail
make deps
make codegen

ivar runs it with bash inside the new worktree, and every branch you cut below runs it, so each agent starts from a working tree instead of a broken build. The setup script guide lists the variables the script gets and has a Flutter version (flutter pub get, build_runner, pod install, secrets).

A main feature and one subfeature per slice

Create the main feature and promote the repo in it first:

ivar feature create figma-proto
ivar feature promote figma-proto app

Order matters. A subfeature's branch is cut from its parent's branch, and that branch only exists once the parent has promoted the repo. If you promote a child first, ivar asks to promote the parent for you, and without a terminal it refuses with the exact ivar feature promote command to run — it never cuts the child from main behind your back.

Now add one subfeature per slice and promote the repo in each:

ivar feature create onboarding --parent figma-proto
ivar feature promote onboarding app
ivar feature create checkout --parent figma-proto
ivar feature promote checkout app
ivar feature create profile --parent figma-proto
ivar feature promote profile app

Each child has its own branch and worktree, based on figma-proto. The Subfeatures section of the features guide is the short reference for this flow.

Before the children start, commit anything two of them would both edit on figma-proto: new dependencies in pubspec.yaml or package.json, the route table, theme tokens. Each child then owns its own files, and integration has nothing to conflict on.

One agent per slice

Open a session on the main feature and hand the split to /ivar-subfeatures:

ivar session start figma-proto

/ivar-subfeatures figma-proto

The skill creates and promotes the children if you have not, then writes each child's plan from its slice of the prototype: the screens it owns, the Figma frame links, the checks to run. It approves those plans and starts one detached session per child. For each child it prints the command that launches your harness in that session; paste each into its own terminal. In each child session, run /ivar-execute.

Each session works in its own worktree, so the agents never touch each other's files, index or HEAD. Each session also gets the same harness config and the same MCP servers, Figma included.

Watching the tree

From any terminal, look at the whole tree:

ivar feature status figma-proto --recursive

After onboarding and checkout have been folded back, it looks like this:

Subtree:
  figma-proto  state active  repos 1  blocked by: profile (active)
    checkout  state integrated  repos 1
    onboarding  state integrated  repos 1
    profile  state active  repos 1

The main feature lists the children that still block it. Once profile is integrated, nothing does.

Folding slices back

When a child's run finishes, quit its harness so its session ends, then integrate it from the figma-proto session. /ivar-subfeatures does this for you as each child finishes; by hand it is one command:

ivar feature integrate onboarding

Integration requires the child's plan gate to be approved, which the skill did when it wrote the plan. If you skip the skill, write the child's plan before you approve it:

ivar plan create onboarding plan
ivar plan approve onboarding plan

Approving the empty scaffold passes the gate and gives the child's agent nothing to build. The child's work lands on the figma-proto branch and the child closes as integrated. A merge conflict fails the command; fix it on the child's branch and run it again. Repeat for checkout and profile.

One pull request

With every child integrated, the main feature carries all three slices. Preview the delivery first:

ivar feature deliver figma-proto --preview

The preview writes nothing. It reads the branch, the remote, the base and any existing pull request, and prints a fingerprint. When it looks right, apply it with the fingerprint the preview printed:

ivar feature deliver figma-proto --fingerprint <fp>

That pushes the figma-proto branch and opens one pull request against main. Creating the pull request needs a GitHub remote; with a local remote, delivery only pushes. The delivery guide covers the details, including updating a pull request that already exists.

When you don't need ivar

If you use one harness on one repo and never run work in parallel, you may not need any of this. Commit an .mcp.json with the Figma server, use git worktree add when you want a second branch checked out, and move on.

ivar starts paying off when several agents run at once, possibly in different harnesses, and each needs the same MCP servers, the same setup script and an isolated worktree, with a way to fold the pieces back into one change.

One feature, three repos: a walkthrough — the multi-repo counterpart, with scope that grows mid-feature.
Who ivar is for — single-repo parallel work and multi-repo work, side by side.
Quickstart — create a hall and your first feature.

One feature, three repos: a walkthrough

Gabriel Menezes — Wed, 30 Sep 2026 00:56:35 +0000

A field that crosses three repos

You need to add a currency to invoices. The API has to store and return it, the web app has to show it, and somewhere in between a shared types package describes what an invoice looks like. Three repositories, one change.

Why a single agent session across repos matters is covered in the context problem nobody solved. This post is the practical side: the commands, in order, for one feature that touches all three.

The hall

Create the hall as its own git repo and register the three repositories in it:

mkdir acme-hall && cd acme-hall && git init
ivar init
ivar repo add api git@github.com:acme/api.git
ivar repo add web git@github.com:acme/web.git
ivar repo add types git@github.com:acme/types.git

Each one lands in ivar.json under repos. That file is the hall's manifest: which repos exist, where they come from, which harnesses and MCP servers every session gets. Nothing is promoted yet, so every repo sits on its default branch, read-only.

One feature, two repos to start

Create the feature and promote the two repos you know you need:

ivar feature create billing-currency
ivar feature promote billing-currency api
ivar feature promote billing-currency web

Promoting a repo cuts a billing-currency branch in it and gives it a worktree the feature can write to. types stays on its default branch as read-only context.

Start a session:

ivar session start billing-currency

One session sees both promoted repos side by side, plus types as read-only. The agent can change the API handler and the web component in the same conversation, and it can read the shared types to see what an invoice looks like today.

Scope grows mid-way

Halfway through, the agent reports the obvious: the invoice type lives in types, and both the API and the web app import it. The currency field has to go there first, or the other two changes won't compile against each other.

You don't need to stop the session or start over. From another terminal, promote the third repo:

ivar feature promote billing-currency types

types gets its own billing-currency branch and worktree, and the session can now write to it. The agent adds the field to the shared type and carries on with the API and the web app. The features guide covers promotion in more detail.

Where things stand

Check the feature:

ivar feature status billing-currency

Feature `billing-currency` (branch: billing-currency):
  api  ready  worktree present  base: main
  types  ready  worktree present  base: main
  web  ready  worktree present  base: main

Three repos, one branch name, each based on its own main. No list of branches to keep in your head.

Delivering together

When the work is done, preview the delivery:

ivar feature deliver billing-currency --preview

The preview writes nothing. For each promoted repo it reads the branch, the remote, the base and any existing pull request, then computes one fingerprint over all three. If any repo changes after you read the preview, the fingerprint no longer matches and apply refuses.

Apply it with the fingerprint the preview printed:

ivar feature deliver billing-currency --fingerprint <fp>

That pushes the billing-currency branch in each repo and opens the three pull requests together, each with a comment linking its siblings, so a reviewer on the web PR can find the API and types PRs.

Creating pull requests needs GitHub remotes. With local remotes, delivery only pushes. The delivery guide covers updating existing pull requests and delivering a subset of repos with --only.

What you didn't do

Cloning, branching, cross-linking pull requests and re-explaining context to fresh sessions were all handled by the feature, including when the scope grew mid-way.

One repo, many agents: parallel features from a Figma prototype — the single-repo counterpart, with subfeatures and one pull request.
MCP servers in a hall — declare MCP servers once and every session across the three repos gets them.
Quickstart — create a hall and your first feature.

Git worktrees are great. They stop at the repo boundary.

Gabriel Menezes — Tue, 29 Sep 2026 16:15:37 +0000

What the worktree posts get right

Git worktrees (git worktree add) have become an indispensable primitive in modern software engineering and agentic workflows. Most community articles explaining how to use git worktrees for AI coding agents get the core single-repository mechanics completely right:

Zero Stash and Context Switch Overhead: You can launch an agentic session on an isolated feature branch without stashing uncommitted local work or altering your active working directory.
Shared Object Database: Worktrees share the parent repository's .git object store. Creating a worktree takes milliseconds because Git simply writes a lightweight .git text file pointing to .git/worktrees/<id> in the main repository, avoiding the disk and network overhead of cloning full repository copies.
Independent Index Files: Each worktree maintains its own independent staging area (index), HEAD ref pointer, and reflog. This allows multiple agent sessions to run in parallel on different feature branches without encountering lock contention or file collision.

The shared object store is what makes a worktree cheap, and it is also what makes it stop at the repository it belongs to.

For single-repository engineering, git worktrees provide an ideal local execution environment. The agent operates inside an isolated file tree, language servers index files correctly, build tools run natively, and git status tracks changes cleanly.

However, modern software applications rarely reside in a single repository. The moment a software feature spans multiple repositories, the single-repo worktree model encounters a hard structural boundary.

The three-repo change

Consider a routine architectural task in a polyrepo ecosystem: modifying an API contract. The feature spans three distinct git repositories:

api-service: The Rust backend implementing the updated endpoint payload.
web-frontend: The TypeScript application consuming the API response.
docs-site: The documentation repository hosting public API reference specs.

To execute this change with an AI coding agent, you require a composite workspace configuration:

Active edit capability on branch feature-auth inside api-service.
Active edit capability on branch feature-auth inside web-frontend.
Read-only reference access on default branch main inside docs-site.

Using raw git worktree commands manually requires executing a tedious multi-step sequence across three separate repository paths:

# Manual worktree creation across three repos
git -C ~/repos/api-service worktree add -b feature-auth ../worktrees/api-feature-auth
git -C ~/repos/web-frontend worktree add -b feature-auth ../worktrees/web-feature-auth
git -C ~/repos/docs-site worktree add ../worktrees/docs-main main

# Create a temporary workspace directory and symlink worktrees
mkdir -p ~/workspaces/feature-auth
ln -s ~/worktrees/api-feature-auth ~/workspaces/feature-auth/api
ln -s ~/worktrees/web-feature-auth ~/workspaces/feature-auth/web
ln -s ~/worktrees/docs-main ~/workspaces/feature-auth/docs

Executing these steps manually for every feature task is slow, repetitive, and error-prone. Consequently, developers build shell scripts to automate multi-repository worktree assembly.

Writing the script anyway

Here is a typical, 60-line bash script that developers construct to automate multi-repository worktree setup for AI agent sessions:

#!/usr/bin/env bash
set -euo pipefail

FEATURE_NAME="${1:-}"
if [[ -z "$FEATURE_NAME" ]]; then
  echo "Error: Feature name required."
  echo "Usage: $0 <feature-name>"
  exit 1
fi

WORKSPACE_DIR="$HOME/.workspaces/$FEATURE_NAME"
mkdir -p "$WORKSPACE_DIR"

declare -A REPOS=(
  ["api"]="$HOME/repos/api-service"
  ["web"]="$HOME/repos/web-frontend"
  ["docs"]="$HOME/repos/docs-site"
)

echo "Initializing multi-repo worktrees for feature: $FEATURE_NAME"

for NAME in "${!REPOS[@]}"; do
  REPO_PATH="${REPOS[$NAME]}"
  TARGET_WORKTREE="$REPO_PATH/../worktrees/$NAME-$FEATURE_NAME"

  if [[ "$NAME" == "docs" ]]; then
    # Read-only reference repository stays checked out on main
    echo "Creating reference worktree for $NAME on main..."
    git -C "$REPO_PATH" worktree add "$TARGET_WORKTREE" main 2>/dev/null || true
  else
    # Feature repositories check out feature branch
    echo "Creating feature worktree for $NAME on branch $FEATURE_NAME..."
    git -C "$REPO_PATH" worktree add -b "$FEATURE_NAME" "$TARGET_WORKTREE" 2>/dev/null || true
  fi

  # Symlink worktree into unified workspace folder
  ln -sfn "$TARGET_WORKTREE" "$WORKSPACE_DIR/$NAME"
done

# Create combined harness instructions
cat <<EOF > "$WORKSPACE_DIR/CLAUDE.md"
# Multi-Repo Workspace Context: $FEATURE_NAME
- api/: Rust backend service (editable feature worktree)
- web/: TypeScript web application (editable feature worktree)
- docs/: Documentation site (reference context only, DO NOT EDIT)
EOF

echo "Multi-repo workspace materialized at: $WORKSPACE_DIR"
cd "$WORKSPACE_DIR" && claude

This script automates worktree creation, symlinks the directories into a unified workspace folder, generates a basic CLAUDE.md, and launches the agent harness.

While this script works for basic local demos, attempting to rely on it in production engineering environments reveals four fundamental limitations.

Four things the script can't do

While an ad-hoc shell script automates directory symlinking, it lacks the technical infrastructure required for reliable, safe multi-repository agent execution.

What it needs to do	What the script does instead
Guard writes to reference repos	Relies on a soft prompt rule
Keep branches and lifecycle aligned	Leaves dirty and orphaned trees
Materialise instructions	Dirties tracked files in each repo
Deliver the feature	Pushes each branch on its own

1. POSIX Filesystem Write Protection

The shell script creates worktrees on disk using standard user write permissions (0755/0644). To restrict modifications in docs/, the script relies exclusively on a text instruction inside CLAUDE.md: "docs/: reference context only, DO NOT EDIT".

Under high context load or multi-step reasoning tasks, language models non-deterministically violate prompt instructions. An agent fixing a broken build or lint error will edit files in docs/ directly, mutating git state in a reference repository. The script cannot enforce write restrictions at the operating system layer.

2. Session Lifecycle and Branch Alignment

When an agent session finishes or crashes, the script leaves active worktrees and branches dangling across multiple repository directories. If a session fails midway:

Worktree lock references persist inside .git/worktrees/ across individual repos.
Re-running the script throws errors because branches or worktree paths already exist.
Developers must manually navigate to each repo directory to run git worktree prune and delete orphaned feature branches.

Furthermore, if branch creation fails in one repository (e.g., due to an uncommitted conflict on main), the script leaves the workspace in a partially initialized, inconsistent state across repos without atomic rollback.

3. Clean Instruction Materialization

The script injects instructions by writing a static CLAUDE.md file at the root of the workspace. However, real-world repositories already contain their own provider-native instruction files (e.g., api/CLAUDE.md and web/CLAUDE.md). The script cannot merge or synthesize instructions across repositories.

If the script writes instruction files directly inside individual repository worktrees, it leaves untracked, dirty files in git status that risk being accidentally committed by the agent.

4. Multi-Repo Feature Delivery

Once an agent completes changes across api/ and web/, delivering the feature requires verifying status, pushing feature branches across multiple repositories, and establishing cross-repository pull request references.

The shell script leaves delivery entirely to manual git operations. It cannot verify atomic feature readiness across mounted repositories, track which repositories were actually modified during the session, or trigger synchronized multi-repo branch pushes (deliver). Note that multi-repo delivery coordinates push operations across repositories, rather than attempting complex dependency sorting or automated merge ordering.

Guarding writes with chmod, not with a prompt

The central vulnerability of custom multi-repo worktree scripts is relying on LLM prompt compliance for write protection. Soft prompt instructions and software hooks inevitably fail under context saturation, complex agent reasoning, or raw shell command execution.

Robust write protection requires enforcing file immutability at the operating system layer using POSIX file permission masks (chmod).

if mode & 0o222 != 0 {
    chmod(path, mode & !0o222)?;
}

In an orchestrated View Directory architecture:

Unpromoted Context Worktrees: When a reference repository (such as docs/) is mounted into the session workspace, write bits (0o222) are stripped recursively across its worktree files and directories via clear_write_bits.
Deterministic Kernel Enforcement: If an agent attempts to modify a file inside an unpromoted repository—whether using a file edit tool, a bash output redirection (>), or an automated code modifier—the operating system kernel rejects the write operation immediately with an EACCES (Permission Denied) error.
Promoted Worktrees: Repositories explicitly designated for active editing have write permissions restored (u+w) via restore_write_bits (mode | 0o200), permitting authorized modifications:

chmod(path, mode | 0o200)?;

By operating at the kernel permission layer, write enforcement remains absolute regardless of LLM prompt drift, context saturation, or tool execution style.

Git worktrees provide the essential foundation for local agent workspaces, but scaling them across multiple repositories requires dedicated session orchestration rather than fragile shell scripts. How a View Dir combines those worktrees with a kernel-enforced write guard is covered in what a View Dir is, and the quickstart walks through mounting your first one.

How ivar helps non-technical teams work across multiple repos

Gabriel Menezes — Tue, 29 Sep 2026 16:15:06 +0000

Why this matters if you don't code

You asked a simple question in Slack: "How does the login flow work today?" Two hours later, you received links to three different repositories, a recently merged PR, and an outdated API contract.

Developers use AI agents to debug code. Product managers and tech leads can use them to debug context, and ivar sets that up with a few terminal commands you run once.

If you are a product manager, a designer, a tech lead, or anyone who works around a codebase rather than inside it, you probably hit the same wall: the engineering team maintains five repositories, and you have no single place to understand what lives where, how things connect, or what changed.

Ivar does not require you to write code. It gives you a structured view of a multi-repo codebase that an AI agent can reason over — and that means you can ask questions in plain language and get structured answers.

The Hall: one place for everything

When an engineering team adopts ivar, they create a Hall — a single directory that describes every repository the project depends on, which branch to use, and what instruction files carry the team's conventions.

Think of the Hall as a table of contents for the codebase. It lists each repository by name, points at the right branch, and records the relationships between them. You do not need to know the file structure of five separate repos, or clone them one by one.

The Hall is a file, and it lives in version control. If the team adds a repository, the Hall changes. If a repository is renamed or removed, the Hall changes. The Hall is the source of truth for how the codebase is organised.

Asking questions about the codebase

Once the Hall exists, ivar creates a view directory — a single workspace that contains every repository on the right branch, with the agent's instruction files already set up. An AI agent opened in that directory can read across all the repositories at once.

This is where you benefit without writing code. You can ask the agent:

"What does the API contract look like for the billing feature?" — the agent reads the OpenAPI spec in one repo and can show you the current state.
"Which repos were changed in the last feature delivery?" — the agent sees the git history across all the repos in the view directory.
"What's the relationship between the frontend component and the backend endpoint it calls?" — the agent can trace the connection across repos.
"Run the analysis and show me a report of what changed this week" — the agent executes the analysis tools already configured in the Hall.

You are not reading source code. You are having a conversation with an agent that has read access to everything, and the agent translates the technical details into language you can act on.

Getting insights without engineering time

The typical alternative is asking an engineer to write a summary, run a report, or explain a dependency graph. That is expensive, slow, and stale the moment it is delivered.

With ivar, the agent in the view directory can generate that summary on demand. The Hall already carries the context — which repos exist, how they relate, what the team's conventions are. The agent does not need to be re-introduced to the codebase every time.

This is particularly useful for:

Sprint planning: Ask the agent what changed in the last week and which areas of the codebase are active.
Dependency reviews: Ask the agent to trace how a change in one repo affects the others.
Onboarding: A new team member can ask the agent to explain the project structure, and the agent answers from the Hall's perspective rather than guessing.
Debugging in production: When something breaks, you can ask the agent to look at the recent changes across all repos and identify what might have caused it.

What ivar does not do

Ivar does not replace your project management tool, your CI pipeline, or your engineering team. It is a local tool that gives an AI agent the context it needs to answer questions about a multi-repo codebase. The agent does the reasoning; the Hall provides the structure.

Ivar also does not discover repos automatically. The engineering team defines the Hall: which repos, which branches, which instruction files. Once that is set, everyone on the team can use it.

It does not remove the terminal either. ivar is a command-line tool, and the agents it works with (Claude Code, OpenCode, OMP) run in a terminal. On Linux or macOS you need to:

Install ivar (curl -fsSL https://ivar.run/install | sh) and, for GitHub repos, log in with gh auth login.
Clone the Hall and let ivar fetch its repos: git clone <hall-url> team-hall, then cd team-hall and ivar sync.
Launch your agent in that directory (for example claude) and type /ivar-discovery. From there you ask questions in plain language; discovery only reads the code, so you cannot break anything.
Before a new round of questions, run ivar repo pull so the agent reads the latest code.

An engineer can walk you through it in about fifteen minutes. After that, the terminal is the window you type your questions into.

Getting started

If your engineering team already uses ivar, ask them for the Hall's git URL and for fifteen minutes to run the four steps above with you. The Hall's ivar.json is a small file, and reading it gives you the vocabulary to ask the agent useful questions.

If your team does not use ivar yet, the quickstart guide shows an engineer how to create a Hall. Setting up the Hall itself takes about fifteen minutes, and the return is a single place where everyone on the team, technical or not, can understand how the codebase is organised.

The context problem nobody solved: AI agents across multiple repos — the technical foundation that makes a multi-repo view directory possible.

Figma MCP on OpenCode: fix "Authentication failed"

Gabriel Menezes — Tue, 29 Sep 2026 16:15:05 +0000

The symptom

You add the Figma MCP server to opencode.json and run opencode mcp auth figma. No browser opens. OpenCode prints Authentication failed and exits with status 0, so a script that checks the exit code thinks it worked. The agent then starts without Figma.

Reinstalling OpenCode does not change it, and neither does a new Figma token. The failure happens before any token exists.

Why it fails

MCP servers that use OAuth let a client register itself on the fly, with dynamic client registration. Figma's registration endpoint, https://api.figma.com/v1/oauth/mcp/register, only accepts a short allowlist of client names. OpenCode registers under its own name, which is not on the list, so Figma refuses the registration and OpenCode never gets as far as the browser.

Figma's documentation describes the workaround: register a client ahead of time under a name the allowlist accepts, then run the authorization flow with that client. Doing it by hand means a curl to the registration endpoint, a PKCE flow with a local redirect, and writing the tokens where OpenCode reads them.

The fix in four commands

ivar does those steps for you. Install it, create a hall in an empty directory, declare Figma and authenticate:

curl -fsSL 'https://ivar.run/install?ref=figma-mcp-opencode' | sh
mkdir design-hall && cd design-hall
ivar init --provider opencode
ivar mcp add figma
ivar mcp auth figma --provider opencode

ivar mcp add figma writes the server into the hall's ivar.json and into the opencode.json next to it:

ivar.json

{
  "mcp": [
    { "name": "figma", "type": "http", "url": "https://mcp.figma.com/mcp" }
  ]
}

ivar mcp auth then pre-registers a client for OpenCode under a name Figma accepts, opens the browser for the authorization, listens for the redirect on 127.0.0.1:19876, and writes the tokens into OpenCode's MCP auth store. It reads the store back afterwards, so a run that leaves no tokens is reported as a failure instead of a silent exit 0. Start opencode from the hall directory and the Figma tools are there.

The client secret goes to .ivar/secrets/mcp.env, which stays out of git. Tokens never go into ivar.json, so the file is safe to commit and share.

If Figma changes its allowlist, the registration step answers 403. That is the one place to look, and the error says so.

The next server, the next harness

The same two commands work for other servers. ivar mcp add linear declares Linear's MCP server; OpenCode's own login works for Linear, so ivar mcp auth linear --provider opencode hands the browser step to opencode mcp auth.

Other harnesses read the same declaration. Add Claude Code or OMP to the hall and authenticate every provider it lists, one at a time:

ivar provider add claude-code
ivar sync
ivar mcp auth figma --all-providers
ivar mcp status

ivar provider add only records the harness; ivar sync writes its MCP file from the same ivar.json. Claude Code's own claude mcp login works with Figma, so ivar delegates to it. OMP has no MCP login command, so ivar runs the flow itself and imports the token with omp auth-broker import. ivar mcp status shows which server has credentials on which provider. One MCP config for Claude Code, OpenCode and OMP walks through all three harnesses side by side.

Then mount your repos

The hall you created is the same hall ivar uses to run agents across repositories. Mount the repos your design work lands in, start a session, and every session gets Figma from the same ivar.json, on every branch and worktree, without another login. The quickstart takes it from here.

Do you need this?

If you use only Claude Code, its own Figma login works and you do not need ivar for this. The failure above is specific to Figma's allowlist and to harnesses that register under a name Figma does not accept: OpenCode today, and OMP, which has no MCP login of its own.

Limits

ivar supports three harnesses: Claude Code, OpenCode and OMP.
It runs on macOS and Linux. Windows is not supported, and WSL is untested.
The OAuth flow talks to Figma's servers directly. ivar has no server of its own in the middle.
The Figma MCP server gives your agent read access to files, frames, comments and component metadata. It does not edit designs, and ivar does not sync designs into code.

One MCP config for Claude Code, OpenCode and OMP: where each harness's MCP auth breaks, and one declaration for all three.
One repo, many agents: parallel features from a Figma prototype: Figma MCP in every parallel session on one repository.
Figma integration: the reference page for this setup.

The context problem nobody solved: AI agents across multiple repos

Gabriel Menezes — Tue, 29 Sep 2026 16:14:34 +0000

Why one repo is the unit an agent understands

AI coding agents are fundamentally designed around a single root directory. When you initialize an agentic session—whether using Claude Code, Codex, Aider, or custom CLI execution harnesses—the harness binds directly to the process's current working directory (cwd).

Inside that single repository boundary, the agentic tooling architecture operates cleanly. The harness reads local instruction files such as CLAUDE.md, .cursorrules, or AGENTS.md, indexes the directory tree, connects to local Language Server Protocol (LSP) daemons for symbol resolution and type checking, runs test runners, and inspects git status. The context window is optimized to ingest and edit files relative to that single canonical root.

Everything the harness does well stops at the edge of the directory it was pointed at.

However, modern software engineering rarely lives within a single repository. Enterprise systems and modern cloud architectures are routinely split across polyrepo boundaries: a Rust core backend, a TypeScript frontend client, an OpenAPI contract repo, an infrastructure-as-code repository, and shared internal utility libraries.

When a developer asks an agent to perform a feature task that spans multiple repositories—such as updating a database schema, adjusting an API endpoint, and reflecting those contract changes in a web application—the single-repo architecture breaks down across several distinct vectors:

LSP and Symbol Resolution Failures: Language servers rely on explicit project configuration files (e.g., tsconfig.json, Cargo.toml, go.mod) located at recognized workspace roots. When an agent attempts to inspect code in a sibling directory outside its bound cwd, the LSP cannot resolve cross-repository types or jump-to-definition targets.
Context Window Noise and Index Pollution: Search utilities like grep or file tree crawlers executed by the harness default to searching relative to the active root. If forced to search higher up the filesystem tree, indexing algorithms ingest unrelated build artifacts, node_modules, target binaries, and lockfiles, quickly saturating the LLM context window with irrelevancies.
Git Semantics Breakdown: Git operations (git diff, git status, git commit) execute relative to the repository containing cwd. When an agent edits files in sibling repositories without changing execution directories, git commands fail or apply modifications to the wrong repository context.
Interactive Session Fragmentation: Switching execution directories dynamically within an active agent session resets tool state, loses chain-of-thought context, invalidates cached workspace maps, and frequently leads to agent hallucination regarding file locations.

Because the single repository remains the hard-coded unit of understanding for existing AI harnesses, engineers working across polyrepo architectures are forced to rely on fragile community workarounds.

The five workarounds people actually use

As agentic coding adoption has accelerated across engineering organizations, teams have attempted to bridge the cross-repo context gap. Based on developer surveys, community architecture guides, and technical discussions surrounding multi-repo AI workflows, five primary workarounds have emerged.

Workaround	What it does
Parent workspace directory	Opens `~/projects/` as the agent root
Meta-repository	A parent repo with the others as submodules
Prompt and path hacks	Injects `../repo-b` into the instruction file
MCP context bridge	Exposes the other repos as read-only search tools
Server-mediated orchestration	Hands the work to agents behind an API

1. The Parent "Mega" Workspace Directory

The simplest and most common workaround is pointing the AI harness at a top-level parent folder containing all local repositories:

cd ~/projects
claude

In this layout, ~/projects/ acts as the root, placing ~/projects/backend-api, ~/projects/web-frontend, and ~/projects/shared-schema inside the agent's visible directory hierarchy.

Where it breaks: Git awareness collapses completely. The parent directory ~/projects is not itself a git repository. Standard harness commands like git status or git diff fail immediately with fatal: not a git repository. Furthermore, file search utilities scan across every cloned repository simultaneously, overloading context limits with irrelevant search hits, while language servers fail to establish root boundaries for auto-completion and type checking.

2. The Meta-Repository with Git Submodules

To restore git tracking at the workspace root, teams construct a meta-repository (often called a "repo-of-repos" or workspace wrapper) that links individual repos as git submodules:

/meta-workspace
 ├── .git/
 ├── .gitmodules
 ├── backend-api/     (submodule)
 └── web-frontend/    (submodule)

Where it breaks: Git submodules introduce heavy operational overhead and state desynchronization. Modifying code inside a submodule leaves the parent meta-repository in a modified state, requiring a multi-step commit dance (committing inside the submodule, then committing the updated submodule pointer in the meta-repo). Branching becomes particularly error-prone: checking out a feature branch in the meta-repo does not automatically check out matching branches inside submodules, causing submodules to enter a detached HEAD state and confusing the agent's mental model of branch alignment across services.

3. System Prompt & Relative Path Guidance

Another prevalent strategy relies on injecting explicit relative path directions into system prompts or repository instruction files (CLAUDE.md, .cursorrules, AGENTS.md):

# Multi-Repo Context Rules
- The backend API code is located at `../backend-api`.
- The shared OpenAPI schema is at `../shared-schema/openapi.json`.
- When updating frontend types, read `../shared-schema/openapi.json` first.

Where it breaks: Relying on relative path instructions places the entire burden of path resolution on the LLM's prompt compliance. Under high token loads or multi-step reasoning tasks, models non-deterministically violate relative path boundaries, attempt to write files outside allowed trees, or hallucinate relative directory levels (e.g., ../../backend-api). Additionally, relative paths break bash tool execution: commands run by the agent default to cwd, producing errors when build scripts or test runners expect to be executed from a sibling repository's root.

4. MCP (Model Context Protocol) Context Bridges

With the adoption of MCP, developers construct custom MCP servers that expose search, read, and indexing interfaces to external repositories. An agent operating within web-frontend calls an MCP tool to fetch function signatures or schema definitions from backend-api.

Where it breaks: MCP bridges provide tool-gated, read-only context retrieval. While an MCP server enables an agent to query code snippets from external repositories, it does not grant the agent the capability to perform native file edits, run local language servers, execute test suites, or manage git commits in the target repository. It solves snippet retrieval but leaves multi-repository execution completely unaddressed.

5. Server-Mediated Orchestration & Multi-Agent Swarms

For large-scale enterprise environments, organizations construct multi-agent server platforms. A centralized orchestrator agent receives an overall task specification, decomposes it into repository-specific sub-tasks, and dispatches individual agent instances to execute asynchronously against remote repositories via API calls.

Where it breaks: Server-mediated multi-agent swarms sacrifice the local, interactive developer-in-the-loop workflow. Communication between agents occurs via natural language summaries sent over network APIs, introducing significant latency, high token consumption, and compounding translation errors. When a multi-repo build fails, diagnosing which agent introduced the breaking change across asynchronous API boundaries is difficult and time-consuming.

What every workaround has in common

Evaluating these five approaches side-by-side reveals a fundamental structural pattern:

Workaround Strategy	Git Integration	Local Test Execution	Write Protection	Operational Friction
Parent Workspace Dir	Broken (`not a git repo`)	Unreliable	Unprotected	Low
Meta-Repo / Submodules	Complex (Detached HEAD)	Local only	Unprotected	High
Prompt Path Hacks	Single repo only	Fails on relative paths	Soft / Prompt-based	Low
MCP Context Bridge	None (Tool abstraction)	None (Read-only)	Read-only	Medium
Multi-Agent Swarms	Isolated per agent	Asynchronous / Remote	Isolated per agent	Very High

Every community workaround makes a fundamental trade-off between workspace visibility, execution capability, and write protection.

None of these approaches provides a real Git worktree on the same feature branch across multiple repositories with write access guarded deterministically at the filesystem layer.

They inevitably fall into one of three failure modes:

They compromise git semantics and language server integration by flattening repositories into plain directories or submodules.
They rely on soft, non-deterministic prompt rules or software hooks to control file writes, which fail under context pressure.
They isolate the agent so strictly (via read-only MCP tools or remote swarms) that the agent cannot perform coordinated edits or run cross-repository test suites.

What a view directory is

To overcome the single-repository limitation while preserving native git semantics and execution capabilities, workspace orchestration requires a dedicated abstraction layer: the View Directory (View Dir).

A View Directory is a materialized, session-specific workspace folder constructed dynamically for an agentic session. Rather than duplicating code or creating nested meta-repositories, a View Directory aggregates registered repositories using native operating system symlinks pointing directly to real Git worktrees.

Each entry is a symlink to a real worktree. Promotion decides which of them the kernel will let the agent write to.

When an agent session initializes within a View Directory:

Promoted Repositories: Repositories where active code modifications are planned are mounted as Git worktrees checked out on the exact same feature branch (e.g., feature-x).
Unpromoted Context Repositories: Repositories included solely for reference are mounted as Git worktrees checked out on their default branch (e.g., main).
Instruction Resolution: Provider-native instruction files (CLAUDE.md, AGENTS.md) at the root of the View Dir are dynamically synthesized from a canonical hall configuration (HALL.md), giving the agent unified multi-repo instructions without dirtying individual repository trees.

Because each entry inside a View Directory points to a genuine Git worktree, language servers process cross-repo imports seamlessly through symlinks, build utilities run locally, and git commands maintain total integrity. The concepts page covers the rest of the model.

Read access is not the hard part — write access is

Exposing multiple repositories for reading is trivial; any file crawler or MCP server can ingest text from sibling directories. The true technical challenge in polyrepo agentic development is enforcing strict write isolation.

When an AI agent operates inside a multi-repository workspace, language models frequently attempt unauthorized or out-of-scope file modifications. For example, while updating a frontend component to handle an API change, an agent might attempt to edit a shared library file to fix a lint error, accidentally mutating git state in a shared context repository.

Why Prompt-Based and Hook-Based Guards Fail

Traditional agent frameworks attempt to enforce write safety through soft boundaries:

System Prompt Instructions: Advising the model "Do not modify files inside the /docs or /lib directory". As context windows fill and reasoning chains complexify, models non-deterministically ignore prompt constraints.
PreToolUse Hooks: Intercepting file-writing tool invocations in software. Hooks add execution latency, are tied to specific harness implementations, and fail to prevent writes executed via raw shell commands (such as echo, sed, or build script output redirection).

POSIX Filesystem Guarding (`chmod`)

To guarantee absolute safety, write protection must operate below the LLM layer, enforced deterministically by the operating system kernel.

In ivar, write safety is enforced at the POSIX filesystem level using file permission masks (chmod). Unpromoted context repositories mounted inside a View Directory are stripped of write bits across their entire worktree tree:

if mode & 0o222 != 0 {
    chmod(path, mode & !0o222)?;
}

When an unpromoted repository is mounted:

clear_write_bits applies mode & !0o222 recursively to every file and folder in the repository's worktree.
If an agent attempts to modify a file in an unpromoted repository—whether using a file edit tool, a bash command redirection, or an automated refactoring script—the OS kernel immediately halts the operation with a deterministic EACCES (Permission Denied) error.
Neither LLM prompt compliance nor harness hook logic is involved in blocking the write; enforcement occurs directly at the kernel boundary.

When a repository is explicitly promoted to active edit status within the session, restore_write_bits selectively re-enables write permissions (u+w), permitting authorized edits:

chmod(path, mode | 0o200)?;

This deterministic mechanism guarantees that read-only context repositories remain strictly immutable throughout the agentic session, regardless of model behavior or shell execution.

Where this leaves you

The single-repository constraint has hindered polyrepo agentic development. While community workarounds—from mega-directories to custom MCP servers—have provided temporary stopgaps, none provide a workspace environment that combines native git execution, multi-repo visibility, and deterministic write protection.

The View Directory pattern replaces soft prompt boundaries and artificial folder structures with a kernel-enforced, worktree-native workspace primitive. OS-enforced permission masks ensure read-only stability across context repositories, while genuine Git worktrees preserve complete compatibility with local development tools and AI harnesses.

The mechanism behind View Dirs, and the vocabulary it uses, is covered in what a View Dir is and why it exists. To mount your own repositories into one, start with the quickstart.

A code graph for agents that spans repos and parallel features

Gabriel Menezes — Tue, 29 Sep 2026 16:14:30 +0000

Where an agent's tokens go

Watch a coding agent start on an unfamiliar change and most of the early turns
look the same. It greps for a name, opens three of the matches, finds an import,
opens that file, greps for the caller, opens two more. Each read puts a whole
file into context, most of which has nothing to do with the question. By the
time it knows where the change goes, it has spent a large share of its budget on
navigation.

A code graph shortens that loop. If the agent can ask "who calls
renderInvoice, and what does it touch" and get the answer with the relevant
source attached, it skips the grep-read-grep cycle. That part is not new.

Two things about how ivar is used made the usual shape of a code graph a poor
fit.

The change spans repositories. A hall mounts an API, a web client and a
shared package side by side. The interesting edges are between them: the web
client's HTTP request and the API route that serves it, or a
type exported by the shared package and used in both. An index built per repo
does not have those edges.

Several features run at once. Each feature is its own branch, checked out as
its own set of worktrees, often with an agent working in each. A graph scoped to
a folder is built for one checkout. Point it at five feature checkouts and you
either index the same repo five times or answer every session from one of them,
which means some agents see code that is not on their branch.

The design

One base, one layer per feature

ivar graph keeps a single SQLite database for the hall at .ivar/memory.db.
It holds a base index of each repo's default branch, shared by every
session. On top of it, each feature gets a layer that holds only the files
the feature changed, committed or not.

A feature session reads its own layer first and the base for everything else. A discovery session reads the base.

A feature usually changes tens of files, so a layer is small next to the base.
Queries from a feature session resolve symbols against the layer first and fall
back to the base, which is how an agent sees its own edits without the graph
duplicating the rest of the repo.

Extraction uses tree-sitter and runs in parallel. Base indexing is incremental:
ivar diffs each repo against the commit it last indexed and checks file size
and modification time, so a rerun parses only what moved.

Freshness on every call

A layer goes stale the moment the agent edits a file. Asking the agent to call a
reindex tool after each edit works until it forgets. So before every query the
MCP server compares the layer with the worktree and reindexes the files that
changed.

That check has to be cheap to run on every call. On a feature with 177 changed
files it took about 18 ms per call, and about 21 ms right after an edit.

If the layer cannot be refreshed, the call fails with an error. It does not
quietly answer from the base: an answer about code that is no longer on disk is
the kind of wrong an agent acts on with confidence.

One query that returns enough to act on

The MCP server advertises one tool by default, graph_explore. The agent passes
symbol names, paths, or a short intent, several at once. The answer includes:

the flow between the symbols it named,
the line-numbered source of the most relevant files, cut to a size budget,
the blast radius of each definition: its callers and type uses,
a ready Next: call with a paths argument listing the files that did not fit.

The source is the part that removes reads. The Next: hint is the part that
keeps the agent from falling back to opening files one at a time: a follow-up
with paths returns up to 12 whole files in one call.

The other tools (callers, impact, affected tests, paths and more) are available
behind ivar graph mcp --tools all, and the queries have CLI equivalents, which
matters for providers such as omp that do not pass MCP servers to subagents. A
subagent can run ivar graph explore renderInvoice in a shell and get the same
answer.

What it changed in a benchmark

We ran agents on the same fixture with and without the graph, using the same
model and the same task prompt in both arms. The fixture is two repositories: a Fastify API and a
React web app that calls it.

Discovery

The agent explores the fixture to answer a question about how the code works,
and its answer is scored against a hand-built answer key. Three runs per arm.

	With `ivar graph`	Without a graph
Median tokens	460k	738k
File reads	0	12 to 28
Answer-key coverage	93 to 94 %	91 to 94 %

The graph arm answered as completely while reading no files; the source it
needed arrived inside the query results. Tokens fell by about 38 %.

Implementation

The agent implements a change in the fixture that has to pass an acceptance
suite. Five runs per arm, and every run in both arms passed.

	With `ivar graph`	Without a graph
Median tokens	1.53 M	1.61 M
Median file reads	6	26

Here the token saving is small, about 5 %. Most of an implementation run is likely
spent editing, running tests and reading their output, and the graph does not
help with that. File reads still fell from 26 to 6, and the reads that remain
are the ones the provider requires before it lets an agent edit a file.

On a real hall

The fixture is small, so we also measured the graph on a working hall of about
29,000 files, which indexed to 144,000 symbols and 1.9 million edges.

Measure	Result
Index size	370 MB
Cold index	77 s
Reindex, no changes	0.17 s
MCP server startup	about 5 ms
`graph_explore`	12 to 80 ms
Callers query	0.4 ms
Impact query	0.2 ms

Caveats

These are small samples: three and five runs per arm, on one fixture, with one
model. The discovery answer key was built by hand, so coverage is a judgment against
it, not an absolute measure. Token counts vary run to
run, which is why the tables report medians and ranges rather than a single
number. The implementation result in particular should be read as "fewer reads
for about the same cost", not as a large saving.

Try it

Build the index from the hall root:

ivar graph index

The first run also registers the graph MCP server in ivar.json (pass
--no-mcp to skip it).

Then run ivar sync to write the provider configs, and start a feature session.
ivar sync also keeps the base index current from then on, and ivar doctor
reports repos whose index has fallen behind.

New to ivar? The quickstart mounts your first hall and opens a
feature in a few minutes; the graph comes with it.

The Code graph guide covers layers and limits, and the
reference lists every subcommand and MCP tool.

Database with Prisma ORM, Docker and Postgres - NestJs with Passport #02

Gabriel Menezes — Fri, 21 Jan 2022 22:34:06 +0000

In the last post start with a blank configuration, understand how to NestJs works with routes, controllers, and services. Saw how easy is to set up Fastify to optimize our app.

Now, will set up the database and ORM for interacting and storing our data. We use PostgreSQL for the database using docker to create a default container for the app, will use Prisma for ORM because is the best Orm of the moment for interacting with the database.

Docker Container

Now that we have our app up, let's containerize it.

Start by creating the following files in the project's root directory:

Dockerfile - This file will be responsible for importing the Docker images, dividing them into development and production environments, copying all of our files, and installing dependencies.
docker-compose.yml - This file will be responsible for defining our containers, required images for the app other services, storage volumes, environment variables, etc.

Open the Dockerfile and add

# Dockerfile

FROM node:alpine As development

WORKDIR /usr/src/app

COPY package*.json ./

RUN yarn add glob rimraf

RUN yarn --only=development

COPY . .

RUN yarn build

FROM node:alpine as production

ARG NODE_ENV=production
ENV NODE_ENV=${NODE_ENV}

WORKDIR /usr/src/app

COPY package*.json ./

RUN yarn add glob rimraf

RUN yarn --only=production

COPY . .

COPY --from=development /usr/src/app/dist ./dist

CMD ["node", "dist/main"]

Open the docker-compose.yml file and add the following code

# docker-compose.yml

version: "3.7"

services:
  main:
    container_name: main
    build:
      context: .
      target: development
    volumes:
      - .:/usr/src/app
      - /usr/src/app/node_modules
    ports:
      - 3000:3000
    command: yarn start:dev
    env_file:
      - .env
    networks:
      - api
    depends_on:
      - postgres
  postgres:
    image: postgres:13
    container_name: postgres
    networks:
      - api
    env_file:
      - .env
    ports:
      - 5432:5432
    volumes:
      - pgdata:/var/lib/postgresql/data
networks:
  api:
volumes:
  pgdata:

Create a .env file and add the PostgreSQL credentials

# .env

# PostgreSQL
POSTGRES_USER=nestAuth
POSTGRES_PASSWORD=nestAuth
POSTGRES_DB=nestAuth

By default, Fastify listens only on the localhost 127.0.0.1 interface. For we access our app from other hosts we need to add 0.0.0.0 in the main.ts

// src/main.ts

await app.listen(3000, "0.0.0.0");

Awesome, we have our dockerized, and let's go test then. Run in the terminal for development

docker-compose up

And our app is Running 👏

Prisma ORM

Prisma is an open-source ORM, it is used as an alternative to writing plain SQL, or using another database access tool such as SQL query builders (like knex.js) or ORMs (like TypeORM and Sequelize).

Start installing Prisma CLI as a development

yarn add Prisma -D

As a best practice invoke the CLI locally by prefixing it with npx, to create your initial Prisma setup using the init command

npx prisma init

This command creates a new Prisma directory with the following contents

schema.prisma: Specifies your database connection and contains the database schema
.env: A dotenv file, typically used to store your database credentials in a group of environment variables

By default your database connection it's set to postgresql

// prisma/schema.prisma

generator client {
  provider = "prisma-client-js"
}

datasource db {
  provider = "postgresql"
  url      = env("DATABASE_URL")
}

How our connection type is correct, we will set the DATABASE_URL in .env

DATABASE_URL="postgresql://nestAuth:nestAuth@postgres:5432/nestAuth"

Remember to add in .env in .gitignore and create a .env.example before creating the repository in Github

Generating the Prisma Client requires the schema.prisma file. COPY prisma ./prisma/ copies the whole Prisma directory in case you also need the migrations.

# Dockerfile

FROM node:alpine As development

WORKDIR /usr/src/app

COPY package*.json ./

# Here Prisma folder to the container
COPY prisma ./prisma/

RUN yarn add glob rimraf

RUN yarn --only=development

COPY . .

RUN yarn build

FROM node:alpine as production

ARG NODE_ENV=production
ENV NODE_ENV=${NODE_ENV}

WORKDIR /usr/src/app

COPY package*.json ./

# Here Prisma folder to the container
COPY prisma ./prisma/

RUN yarn add glob rimraf

RUN yarn --only=production

COPY . .

COPY --from=development /usr/src/app/dist ./dist

CMD ["node", "dist/main"]

First Model

Now to test the connection we will be creating a User model, inside schema.prisma insert

// prisma/schema.prisma

model User {
  id        Int            @id @default(autoincrement())
  email     String         @unique
  name      String
  password  String
  createdAt DateTime       @default(now())
  updatedAt DateTime       @updatedAt
}

With your model in place, you can generate your SQL migration files and run them against the database. Here I use migrate dev for a run in development mode and set init name for the migration

Before this you need up your docker

docker-compose up

and edit your .env file

DATABASE_URL="postgresql://nestAuth:nestAuth@localhsot:5432/nestAuth"

Always you run prisma migrate you need change the database host to localhost after you rollback to name of your database container.

npx prisma migrate dev --name init

Rollback .env file

DATABASE_URL="postgresql://nestAuth:nestAuth@nestauth:5432/nestAuth"

Good News, is our configuration is working, now our database is in sync with our app 👏

Setup Prisma

We will want to abstract away the Prisma Client API for database queries within a service. so let's create a new PrismaService that takes care of instantiating andPrismaClient to connecting to your database.

Create a prisma.service.ts inside src folder

// src/prisma.service.ts

import { INestApplication, Injectable, OnModuleInit } from "@nestjs/common";
import { PrismaClient } from "@prisma/client";

@Injectable()
export class PrismaService extends PrismaClient implements OnModuleInit {
  async onModuleInit() {
    await this.$connect();
  }

  async enableShutdownHooks(app: INestApplication) {
    this.$on("beforeExit", async () => {
      await app.close();
    });
  }
}

First Service

Now we can write a user service to make database calls. So NestJs CLI has a command nest g to generate services, controllers, strategies, and others structures. For now, we run

nest g service users

Before start create a service we need to generate types of Prisma Model, we can generate with this

npx prisma generate

Inside the src folder the command creates a users folder with users.service.ts and the file test users.service.spec.ts. To test our database connection let's create a two services

user: to get a user using the Prisma interface Prisma.UserWhereUniqueInput forget user by unique columns
createUser: to create a new user using data from interface Prisma.userCreateInput that get auto the fields when the model needs to create a new register

And inside the createUser we need to encrypt the user password, so let's create a provider for this, in the src folder create a providers folder and create a password.ts file

// src/providers/password.ts

import { Injectable } from "@nestjs/common";
import * as bcrypt from "bcrypt";

const SALT_OR_ROUNDS = 10;

@Injectable()
export class PasswordProvider {
  async hashPassword(password: string): Promise<string> {
    return bcrypt.hashSync(password, SALT_OR_ROUNDS);
  }

  async comparePassword(password: string, hash: string): Promise<boolean> {
    return bcrypt.compareSync(password, hash);
  }
}

The class has two methods, hashPassword and comparePassword to encrypt and compare the password using brcypt. Inside the UsersService class we need to add in the constructor the provider PasswordProvider for use in the methods.

// src/users/users.service.ts

import { HttpException, HttpStatus, Injectable } from "@nestjs/common";
import { PrismaService } from "../prisma.service";
import { User, Prisma } from "@prisma/client";
import { PasswordProvider } from "src/providers/password";

@Injectable()
export class UsersService {
  constructor(
    private prisma: PrismaService,
    private passwordProvider: PasswordProvider
  ) {}

  async user(
    userWhereUniqueInput: Prisma.UserWhereUniqueInput
  ): Promise<User | null> {
    const user = await this.prisma.user.findUnique({
      where: userWhereUniqueInput,
    });

    delete user.password;

    return user;
  }

  async createUser(data: Prisma.UserCreateInput): Promise<User> {
    const userExists = await this.prisma.user.findUnique({
      where: { email: data.email },
    });

    if (userExists) {
      throw new HttpException("User already exists", HttpStatus.CONFLICT);
    }

    const passwordHashed = await this.passwordProvider.hashPassword(
      data.password
    );

    const user = await this.prisma.user.create({
      data: {
        ...data,
        password: passwordHashed,
      },
    });

    delete user.password;

    return user;
  }
}

With service created let's create a controller for route use that

nest g controller users

So this command create users.controller.ts and our test file inside src/users, so let's create two functions in the controller

signUpUser: For run createUser service and return a data from them
getUserProfile: Get an id of the user sent by the route and run the user service to find them

// src/users/users.controller.ts

import { Body, Controller, Get, Param, Post } from "@nestjs/common";
import { User } from "@prisma/client";
import { UsersService } from "./users.service";

// Set prefix route for this group. Ex.: for get profile /users/8126321
@Controller("users")
export class UsersController {
  constructor(private readonly usersService: UsersService) {}
  // Create user -> POST /users
  @Post()
  async signupUser(
    @Body() userData: { name: string; email: string; password: string }
  ): Promise<User> {
    return this.usersService.createUser(userData);
  }

  // Get user Profile -> GET /users/:id
  @Get("/:id")
  async profile(@Param("id") id: number): Promise<User> {
    return this.usersService.user({ id: Number(id) });
  }
}

Inside the users.module.ts file we need to add the providers, exports, and controllers array.

// src/users/users.module.ts

import { Module } from "@nestjs/common";
import { PrismaService } from "src/prisma.service";
import { PasswordProvider } from "src/providers/password";
import { UsersController } from "./users.controller";
import { UsersService } from "./users.service";

@Module({
  providers: [PasswordProvider, UsersService, PrismaService],
  exports: [UsersService],
  controllers: [UsersController],
})
export class UsersModule {}

And pass the UsersModule to the AppModule for use.

//src/app.module.ts

import { Module } from "@nestjs/common";
import { AppController } from "./app.controller";
import { PrismaService } from "./prisma.service";
import { UsersModule } from "./users/users.module";
import { UsersService } from "./users/users.service";
import { PasswordProvider } from "./providers/password";

@Module({
  imports: [UsersModule],
  controllers: [AppController],
  providers: [PrismaService, UsersService, PasswordProvider],
})
export class AppModule {}

Let's Test

Now lets up our docker container

docker-compose up

And that's it! The app is running 👏

So in Postman let's try using the createUser and getProfile routes

curl --location --request POST 'http://0.0.0.0:3000/users' \
--header 'Content-Type: application/json' \
--data-raw '{
    "email": "test@e3x.com",
    "name": "Gabriel Menezes",
    "password": "123123"
}'

curl --location --request GET 'http://0.0.0.0:3000/users/37'

Until Next Time

That is all we are going to cover in this article, we dockerize the app, set up Prisma, and create two routes. In the next piece in the series, we'll create and define our Auth providers for authenticating in our app.

Thank you for reading!

Follow repository to consulting code

mnzsss / nest-auth-explained

🔒 Authentication using JWT and Google with Nest.js Explained

References

Setup Project and Fastify Platform - NestJs with Passport #01

Gabriel Menezes — Thu, 06 Jan 2022 21:49:49 +0000

In this series of posts I will create an Authentication system with Passport using social auth and JWT. Let's use the combination of NestJs + Passport + Fastify to create a complete authentication system.

So in this first part, we start with a blank project and will use the Fastify Platform and understand how NestJs works.

What is NestJs?

NestJs is a framework for building efficient and scalable Node.js server-side applications. It uses robust HTTP Server frameworks like Express or Fastify. NestJs provides a level of abstraction above the common Node.js frameworks and exposes their APIs to the developer. This gives a great amount of freedom to use third-party modules.

Used for writing scalable, testable, and loosely coupled applications. It supports databases like PostgreSQL, MongoDB, MySQL.

Start Project

We will use the @nestjs/cli to create a starter project and clear the files when we don't use them in our project. If you want to see the details, check the official documentation.

First, we install @nestjs/cli globally in your computer and initialize a blank project. I recommend using yarn for installing packages, but you can choose a package manager your preference.

yarn global add @nestjs/cli
nest new nest-auth

And you access the folder and run in VSCode (or in another editor if you prefer).

cd nest-auth
code .

In the image below, you see the file structure, when we have an app module, controller, and service.

Type of blocks in NestJs

Modules: used to organize the code and split features into logical reusable units. Grouped TypeScript files are decorated with “@Module” decorator which provides metadata that NestJs makes use of to organize the application structure.

Providers: also called services, which are designed to abstract any form of complexity and logic. Providers can be created and injected into controllers or other providers.

Controllers: responsible for handling incoming requests and returning appropriate responses to the client-side of the application (for example call to the API).

Configure Fastify Platform

In this project, I choose to use Fastify because it has a much better performance and functionalities than Express.

Fastify provides a good alternative framework for Nest because it solves design issues in a similar manner to Express. However, fastify is much faster than Express, achieving almost two times better benchmarks results. A fair question is why does Nest use Express as the default HTTP provider? The reason is that Express is widely-used, well-known, and has an enormous set of compatible middleware, which is available to Nest users out-of-the-box.

So let's configure that, in main.ts we configure the platform if we use Fastify.

First, we need to install the required package:

yarn add @nestjs/platform-fastify

And in src/main.ts you import FastifyAdapter and NestFastifyApplication for initialize that in NestFactory.create.

// src/main.ts

import { NestFactory } from '@nestjs/core';
import {
  FastifyAdapter,
  NestFastifyApplication,
} from '@nestjs/platform-fastify';
import { AppModule } from './app.module';

async function bootstrap() {
  const app = await NestFactory.create<NestFastifyApplication>(
    AppModule,
    new FastifyAdapter()
  );
  await app.listen(3000);
}
bootstrap();

We don't need any more settings, now Fastify is configured and ready to use 👏

Run First Route

When making a project using @nestjs/cli it creates an example route, so will use that route to test our configuration. In the next tutorials, I explain how routes work in NestJs. Now we want to know if Fastify is working.

Open app.controller file, our see a default route using GET method in / path when using the http://localhost:3000/ the server run getHello function and return a response from AppService

// src/app.controller.ts

import { Controller, Get } from '@nestjs/common';
import { AppService } from './app.service';

@Controller()
export class AppController {
  constructor(private readonly appService: AppService) {}

  @Get()
  getHello(): string {
    return this.appService.getHello();
  }

The AppService has a method called getHello that returns a string Hello World

// src/app.service.ts

import { Injectable } from '@nestjs/common';

@Injectable()
export class AppService {
  getHello(): string {
    return 'Hello World!';
  }
}

So let's send a request using Postman for this route and see what returns

Good news its working 👏

Logger

If you want to get a log always that you send one request you can set this option inside Fastify Adapter

// src/main.ts

async function bootstrap() {
  const app = await NestFactory.create<NestFastifyApplication>(
    AppModule,
    new FastifyAdapter({ logger: true }),
  );

  await app.listen(3000);
}
bootstrap();

Here is an example if you use this option

Until Next Time

That is all we are going to cover in this article, we understood about NestJs and made an initial setup for our project to grow. In the next piece in the series, we'll configure the Database using Prisma, Docker, and Postgresql.

DEV Community: Gabriel Menezes

One MCP config for Claude Code, OpenCode and OMP

Three files for one server

Where the login breaks

Declare once

Authenticate once per server

Do you need this?

Limits

Then add your repos

Related

One repo, many agents: parallel features from a Figma prototype

One repo, one big prototype

The hall with one repo

A main feature and one subfeature per slice

One agent per slice

Watching the tree

Folding slices back

One pull request

When you don't need ivar

Related

One feature, three repos: a walkthrough

A field that crosses three repos

The hall

One feature, two repos to start

Scope grows mid-way

Where things stand

Delivering together

What you didn't do

Related

Git worktrees are great. They stop at the repo boundary.

What the worktree posts get right

The three-repo change

Writing the script anyway

Four things the script can't do

1. POSIX Filesystem Write Protection

2. Session Lifecycle and Branch Alignment

3. Clean Instruction Materialization

4. Multi-Repo Feature Delivery

Guarding writes with chmod, not with a prompt

How ivar helps non-technical teams work across multiple repos

Why this matters if you don't code

The Hall: one place for everything

Asking questions about the codebase

Getting insights without engineering time

What ivar does not do

Getting started

Related

Figma MCP on OpenCode: fix "Authentication failed"

The symptom

Why it fails

The fix in four commands

The next server, the next harness

Then mount your repos

Do you need this?

Limits

Related

The context problem nobody solved: AI agents across multiple repos

Why one repo is the unit an agent understands

The five workarounds people actually use

1. The Parent "Mega" Workspace Directory

2. The Meta-Repository with Git Submodules

3. System Prompt & Relative Path Guidance

4. MCP (Model Context Protocol) Context Bridges

5. Server-Mediated Orchestration & Multi-Agent Swarms

What every workaround has in common

What a view directory is

Read access is not the hard part — write access is

Why Prompt-Based and Hook-Based Guards Fail

POSIX Filesystem Guarding (chmod)

Where this leaves you

A code graph for agents that spans repos and parallel features

Where an agent's tokens go

The design

One base, one layer per feature

Freshness on every call

One query that returns enough to act on

What it changed in a benchmark

Discovery

Implementation

On a real hall

POSIX Filesystem Guarding (`chmod`)