Your Agentic IDE Is Running Blind: Why Your Repo Needs an Environment Contract

dantwoashim / DevContract

Go CLI for repo-first developer onboarding, setup validation, and encrypted local environment sync.

DevContract

DevContract is an open-source repo-first tool for developer onboarding, local setup contracts, and encrypted .env sharing.

It is built for teams that still onboard people through stale docs, copied .env files, chat messages, and tribal knowledge. DevContract lets the repository describe how local development should work, helps teammates receive shared config more safely, and keeps local revision history encrypted on each machine.

Why It Exists

Most teams do local setup with some messy mix of:

• README steps that drift over time
• copied .env files in chat or DMs
• hand-written onboarding checklists
• "ask someone on the team" as the real setup process

DevContract tries to replace that with one repo-owned contract for setup, health checks, and shared local config workflows.

What Makes It Different

• The repo can declare a local setup contract in .devcontract/contract.yaml
• The CLI can bootstrap, validate, and run that contract
• Shared .env updates can move directly between…

View on GitHub

In mid-2026, you are likely paying hundreds of dollars a month for agentic IDEs and CLI tools (like Cursor, Windsurf, or Claude Code) that can write complex production code faster than any human.

Yet, your state-of-the-art AI agent is currently spending 30% of its context window trying to figure out why it can't connect to a local Redis instance, guessing at environment variables that were last documented in a Slack DM from February, and trying to bootstrap itself against a README.md that hasn't been touched since the previous CTO left.

The model isn't the problem. The repository is.

Your repository has no contract. It has no machine-readable way to describe how it is supposed to run locally. So we continue to pay the "it works on my machine" tax, copy-pasting plaintext .env files in direct messages like it's 2012.

I built DevContract after watching the fifth project onboarding in a row collapse into a long, fragmented Slack DM chain. I realized that while we virtualize our servers and automate our deployments, we treat the local machine setup as an afterthought—something solved by tribal knowledge and insecure copy-pasting.

There is a cleaner, local-first path that turns repository configuration into a Git-committed contract, using the SSH keys already sitting on your machine to share environment state securely.

No SaaS. No central cloud accounts. No trusted third-parties.

......

The AI Agent Context Window Tax

When you drop a developer agent into an unbootstrapped repository, it is forced to run blind. It tries to execute test suites or build commands, hits a wall, and starts generating diagnostic loops. It guesses port configurations, hallucinates API key variables, and burns through your context window tokens trying to solve basic environment setup issues.

Claude Code, Cursor, and Cline can all read .devcontract/contract.yaml and understand your environment requirements without hallucinating. When your agent knows exactly what services should be running and what variables should be set, it stops wasting tokens on diagnostics and starts writing code.

This is what a repository-owned setup contract looks like. It is defined in a simple YAML file (.devcontract/contract.yaml) checked directly into Git:

version: 1
project:
  slug: payments-api
  name: Payments API
env:
  required:
    - name: DATABASE_URL
      source: shared
      description: Local Postgres connection string
    - name: STRIPE_API_KEY
      source: developer-local
  public:
    - PORT
    - NODE_ENV
runtimes:
  - node
  - pnpm
services:
  - name: postgres
    host: 127.0.0.1
    port: 5432
    required: true
bootstrap:
  steps:
    - pnpm install
  outputs:
    - path: .env.local
      kind: env
      gitignore: true
doctor:
  checks:
    - name: redis-cache
      type: tcp
      target: 127.0.0.1:6379

This file is versioned with the source code. It explicitly states which variables are required, what runtimes (Node, Go, Docker) must be present, what services must be listening, and what shell steps bootstrap the workspace.

When a developer—or an AI agent—clones this repository, they don't guess. They run three CLI commands:

devcontract init
devcontract bootstrap
devcontract doctor

devcontract doctor executes the contract. It validates your runtimes, pings local TCP ports to ensure backing databases are listening, and checks that every required environment key is present. If something is missing, the tool reports a clear, machine-readable validation error.

......

Treating Your .env Like Source Code: Merge Conflicts, History, and Rollbacks

Every mainstream secrets manager or .env sharing tool treats local configurations with a last-write-wins policy. If you push an update to your database URL and a teammate pushes an API key update ten seconds later, someone’s local config gets clobbered.

We solved this by building a local, encrypted, Git-like version store.

Git solved this problem for source code in 2005. For some reason, we never applied the same thinking to environment configuration. Until now.

DevContract tracks the parent lineage of your environment states. When you update your variables, it records a cryptographic revision hash. When you run devcontract pull to fetch updates:

Clean Auto-Merges: If you changed key A locally and a teammate changed key B on another machine, the engine runs a three-way merge and updates the file automatically.
Conflict Isolation: If you both modified key A to different values, the engine halts, isolates the conflict, and lets you resolve it key-by-key in the terminal.
Local Rollbacks: If a sync goes wrong or you break your local setup, you don't have to guess what changed. You run devcontract backup list and roll your local environment back to a previous, verified state.

Both changes merge cleanly. No clobbered config. No frantic Slack messages.

This has never worked before. Not with any tool.

......

Cryptography Without the Management Overhead

To share environment secrets, teams have traditionally had to choose between two painful options:

1. Trust a SaaS provider: Encrypt your keys, but hand the master decryption keys to a centralized platform (Doppler, Infisical, 1Password) where their cloud databases are a single database breach away from exposing your organization.
2. Infrastructure hell: Manage GPG key rings, configure cloud Key Management Services (KMS), or maintain complex hosted servers (HashiCorp Vault) that require dedicated platform engineering hours.

DevContract takes a local-first, relay-blind approach.

Doppler charges $12/user/month to be the entity that holds your secrets. DevContract charges nothing and holds nothing.

1. Zero-Account Identity You don't register an account. You don't create a password. When you run devcontract init, the CLI looks for your existing SSH key (~/.ssh/id_ed25519).

It performs a birational map conversion (Edwards-to-Montgomery curve mapping) to derive a X25519 transport public/private keypair from your Ed25519 signing key. It is the same approach used in production cryptographic protocols. Your identity is derived securely from infrastructure you already own.

1. Direct P2P Sync (LAN)
   If you push updates and your teammate is on the same Wi-Fi network, DevContract bypasses the cloud entirely. It scans the LAN using mDNS, resolves your teammate's transport key, establishes a direct TCP socket, and negotiates a Noise-secured session to push the updates. The secrets never hit the internet.

2. Operator-Opaque Relay Fallback
   If your teammate is offline or on a remote network, DevContract falls back to a serverless relay.

The CLI generates an ephemeral private key, performs an ECDH key exchange with the recipient’s public key, and encrypts the environment payload using XChaCha20-Poly1305 (binding the ephemeral public key as Additional Authenticated Data to prevent key-substitution attacks).

To resist metadata and traffic analysis, the plaintext payload is padded to a strict 1KB boundary before encryption. The relay (built as a lightweight Cloudflare Worker using Durable Objects for queueing) stores only these encrypted envelopes.

The relay is structurally incapable of reading your environment variables—not because we promise not to, but because the math makes it impossible.

......

How It Compares

If you are evaluating your local configuration stack, here is how the landscape shapes up:

| Feature | DevContract | Doppler | 1Password Secrets | direnv |
| :...... | :...... | :...... | :...... | :...... |
| No Account Required | ✅ | ❌ | ❌ | ✅ |
| Works 100% Offline | ✅ | ❌ | ❌ | ✅ |
| Three-Way Merge | ✅ | ❌ | ❌ | ❌ |
| P2P LAN Sync | ✅ | ❌ | ❌ | ❌ |
| Vendor Holds Master Keys | ❌ (Relay-Blind) | ✅ | ✅ | N/A |
| Repo-Owned Setup Contract | ✅ | ❌ | ❌ | ❌ |
| AI Agent Context-Aware | ✅ (Auto-generates rules) | ❌ | ❌ | ❌ |
| Licensing | ✅ Free & Open Source | ❌ Proprietary | ❌ Paid | ✅ Free & Open Source |

......

Start Right Now

You can replace your Slack .env handoffs and your outdated onboarding checklists right now.

Install the CLI using our installer script (macOS/Linux):

curl -fsSL https://raw.githubusercontent.com/dantwoashim/DevContract/main/scripts/install.sh | bash

(Windows PowerShell alternative: irm https://raw.githubusercontent.com/dantwoashim/DevContract/main/scripts/install.ps1 | iex)

Once installed, initialize your local identity and configure your current repository:

cd your-project-directory
devcontract init

This generates .devcontract/contract.yaml with a starter contract. Replace the placeholder dependency steps, and run:

devcontract bootstrap
devcontract doctor

Invite your teammates by running devcontract invite <username> and start syncing changes securely with devcontract push and devcontract pull.

......

The codebase is open-source and ready for audits. Check out the [DevContract GitHub repository]https://github.com/dantwoashim/DevContract to run it, contribute, or deploy a self-hosted Cloudflare Worker relay.