Don't Let the Agent Guess Your Workspace

The first agent command is where a free coding session usually dies, and it rarely dies from a weak model. It dies because the agent invents a working directory, a start script, and a port, then treats that fiction as fact. I learned to treat that first turn as a permissions problem rather than another exercise in clever prompting. If the workspace has not been proven on disk, why would I let any tool start writing files?

Think of the agent like a courier who never checks the street address printed on the box. You asked for a small route change, and it sprints toward a house that only looks similar from the road. The damage is not theatrical, just a wrong folder, a wrong lockfile, and a server process you never started. Have you watched a coding tool fix a bug by editing a path that exists only inside its context window?

I keep seeing the same shape in developer tools that now call themselves agentic without changing the consent model. The product window opens, the chat box looks harmless, and the model asks almost nothing about your actual machine. Then it proposes npm run dev, invents a src/app/page.tsx file, and talks as if port 3000 already belongs to you. That is not architecture guidance in any serious sense; it is a confident shrug wearing a terminal font.

The teardown I care about is not the onboarding carousel or the animated first-run checklist in the sidebar. It is the short window after you paste a real task and the agent reaches for a shell command. Silent defaults beat your actual repository in that window, and they do it with a tone that sounds helpful. The one fix that mattered for me was boring on purpose: prove the workspace locally, then allow the first command.

Here is the reproducible gate I run from the repository root before any agent is allowed to touch the tree. It refuses to print secret values, and it refuses to start a long-running product process on your behalf. It only writes facts that a later prompt is allowed to cite, and it exits nonzero when the tree is unproven. The snippets below are a lab workflow, not a production benchmark I ran against a public dataset.

#!/usr/bin/env bash
# workspace-gate.sh — lab workflow: fail closed, write facts, never dump env values
set -euo pipefail

ROOT="$(git rev-parse --show-toplevel 2>/dev/null || true)"
if [[ -z "${ROOT}" ]]; then
  echo "GATE_FAIL: not inside a git work tree" >&2
  exit 2
fi

cd "$ROOT"
FACT_FILE="${ROOT}/.workspace-facts.json"
PORT="${PROOF_PORT:-3000}"

pkg="absent"
[[ -f package.json ]] && pkg="present"

lock="absent"
if [[ -f package-lock.json || -f pnpm-lock.yaml || -f yarn.lock ]]; then
  lock="present"
fi

env_example="absent"
[[ -f .env.example ]] && env_example="present"

env_file="absent"
if [[ -f .env || -f .env.local ]]; then
  env_file="present"
fi

if command -v lsof >/dev/null 2>&1; then
  if lsof -iTCP:"$PORT" -sTCP:LISTEN >/dev/null 2>&1; then
    port_state="listening"
  else
    port_state="closed"
  fi
else
  port_state="unknown"
fi

branch="$(git rev-parse --abbrev-ref HEAD)"
dirty="$(git status --porcelain | wc -l | tr -d ' ')"

export GATE_ROOT="$ROOT"
export GATE_FACT_FILE="$FACT_FILE"
export GATE_PORT="$PORT"
export GATE_PKG="$pkg"
export GATE_LOCK="$lock"
export GATE_ENV_EXAMPLE="$env_example"
export GATE_ENV_FILE="$env_file"
export GATE_PORT_STATE="$port_state"
export GATE_BRANCH="$branch"
export GATE_DIRTY="$dirty"

python3 - <<'PY'
import json, os, datetime
facts = {
  "generated_at": datetime.datetime.utcnow().isoformat() + "Z",
  "root": os.environ["GATE_ROOT"],
  "branch": os.environ["GATE_BRANCH"],
  "dirty_files": int(os.environ["GATE_DIRTY"]),
  "package_json": os.environ["GATE_PKG"],
  "lockfile": os.environ["GATE_LOCK"],
  "env_example": os.environ["GATE_ENV_EXAMPLE"],
  "env_file_present": os.environ["GATE_ENV_FILE"],
  "port": int(os.environ["GATE_PORT"]),
  "port_state": os.environ["GATE_PORT_STATE"],
  "allowed_commands": ["git status", "ls", "sed -n '1,40p' package.json"]
}
path = os.environ["GATE_FACT_FILE"]
with open(path, "w", encoding="utf-8") as fh:
    json.dump(facts, fh, indent=2)
    fh.write("\n")
print("GATE_OK wrote", path)
PY

I run those two commands in order, and I refuse to continue when the exit code is anything other than zero. That sounds fussy until you remember how often an agent changes directory into a folder it just hallucinated. chmod +x is not ceremony here; it is the line that makes the gate a real command instead of a gist you never run.

chmod +x workspace-gate.sh
./workspace-gate.sh || exit $?
echo ".workspace-facts.json" >> .gitignore
cat .workspace-facts.json

The JSON file is the only map I paste into the first prompt, because everything else is an invitation to guess. Notice what is missing on purpose: tokens, API keys, file bodies, and any claim that a server is ready. If package_json is absent, why would I let the agent invent a framework tree that your git history cannot explain? If the recorded port is closed, why would I let it debug a five hundred from a process that is not listening?

The prompt I actually send stays short, because the gate already did the only honest work in the session. I tell the model it may not create paths outside root, and it may not assume a framework from vibes alone. I also tell it not to start a server unless I say so, which is slower than letting it rip by exactly one command. That extra command is the whole point of the teardown, not a tax I pay to feel disciplined.

You are working in a proven workspace. Use only .workspace-facts.json.
Do not invent directories, scripts, ports, or frameworks.
If package_json is absent, ask before scaffolding.
If port_state is not listening, do not diagnose HTTP errors.
First reply with: (1) the root you will use, (2) the first command,
(3) what you still do not know. Wait for yes before running anything.

When developers talk about agentic coding this week, they often mean tools that assume the architecture on your behalf. That trend is useful as a warning, because a brownfield repo can put on a greenfield costume in a single turn. I would rather an agent admit ignorance than ship a plausible src directory that never belonged to the project. Cheap generation without a gate is how technical debt arrives before you have even made the first commit.

I treat the free server as a disposable place to confirm an agent can follow the facts file, not as production proof. I do not need a leaderboard for that check; I need a second pair of eyes I can throw away later. Does that mean I trust a remote box with a live env file sitting beside the application code? The gate records env_file_present as a boolean and then stops, which is the entire security story I want in the facts file.

A tiny Node check sits beside the shell script in a JavaScript repo, because lsof is not the only way a port can lie. This lab check tries to bind the port, and a failed bind means something is already listening on that socket. If the bind succeeds, I close the socket immediately and record closed, which is a proof, not a benchmark.

// prove-port.mjs — labeled lab check, not a benchmark
import net from "node:net";

const port = Number(process.env.PROOF_PORT || 3000);
const server = net.createServer();
server.unref();

server.once("error", (err) => {
  if (err && err.code === "EADDRINUSE") {
    console.log(JSON.stringify({ port, port_state: "listening" }));
    process.exit(0);
  }
  console.error("GATE_FAIL: port proof error", err);
  process.exit(2);
});

server.listen(port, "127.0.0.1", () => {
  server.close(() => {
    console.log(JSON.stringify({ port, port_state: "closed" }));
  });
});

node prove-port.mjs
PROOF_PORT=5173 node prove-port.mjs

Put the two outputs next to each other and you get a decision that does not need a meeting or a dashboard. If the facts file says closed and the agent still writes a repro from localhost three thousand, the agent failed the gate. If dirty_files is high and the agent wants to scaffold, I make it stop rather than launder a surprise tree into a dirty workdir. If a lockfile is present and it suggests a different package manager, that suggestion is another invented blank wearing confidence.

Limitations are not a footnote I tack on for tone; they are the reason I still read the first agent reply with suspicion. This gate cannot see containers you did not expose, and it cannot tell a healthy listener from a zombie process on the same port. It will not stop a model from lying in prose after you paste the facts, because a JSON file is not a character witness. If you work in a monorepo with five apps, split facts per package, because one PROOF_PORT is a blunt instrument.

Who should not use this workflow if they want to stay honest about the failure mode I am describing here? Skip it if you need a fully autonomous loop with no human yes sitting between the model and the shell. Skip it if you cannot run local scripts on the machine that holds the repo, because the gate is useless as a story. Skip it if you want an agent to invent a greenfield app in an empty folder, because this gate is for brownfield honesty.

A free tier also will not replace code review, mutation testing, or a staging server that actually resembles production traffic. I still want models that can write tests, review diffs, and wander through a disposable server after the workspace has been proven. I just refuse to start that loop on a map the model drew from a training prior instead of from git. The one fix that mattered was not a better system prompt; it was a fail-closed file that made the first command earn its place.

If you try the script on a throwaway repository, keep the facts file out of version control unless you sanitize the root path. Then watch the first agent turn with the same attention you would give a pull request from a stranger. Did it ask a question about the facts you measured, or did it start guessing the neighborhood again?

Disclosure: This article was prepared as part of MonkeyCode's product outreach.

MonkeyCode provides free models that can run this workflow.