Do Coding Agents Really Need Unrestricted Shell Access?

Vương Nguyên Khang — Sat, 12 Sep 2026 12:22:32 +0000

Exploring a bounded repository capability layer with MCP, AST/LSP code intelligence, guarded writes, and Git context.

Coding agents need access to a repository. They need to read files, search for implementations, follow definitions, change source, and inspect the resulting diff. A general-purpose shell can support all of those tasks.

It can also do almost everything else available to the host account.

That is the trade-off behind my-pi, an open-source experiment in exposing a narrower repository capability surface through the Model Context Protocol (MCP).

The question is not whether shells are bad. Shells are universal, composable, mature, and already present on most developer machines. The narrower question is this:

For ordinary repository work, how much useful capability can we expose without making arbitrary command execution the default interface?

my-pi is an attempt to test that question in code. It is an alpha project, not a claim that one interface fits every coding workflow.

The shell is an excellent abstraction, and a broad authority boundary

When an agent needs to find code, a shell gives it rg, git, language tooling, package managers, build systems, and arbitrary scripts. That generality is why shell-based agents are so effective.

But the interface is not really just “repository access.” It is general command execution with the authority of the host process.

That distinction matters when we decide what an agent should be allowed to do by default. A coding task may need five broad classes of action:

inspect an authorized workspace;
read and search files;
understand code structure and symbols;
perform a bounded mutation;
inspect repository state and diffs.

A shell can do all five. It does not naturally stop at those five.

The thesis behind my-pi is that these operations are valuable enough to expose directly for some workflows, with the boundary visible in the protocol and runtime rather than hidden in a prompt.

Start with explicit workspace authority

The command-line server accepts an explicit workspace:

my-pi-mcp --workspace /path/to/your/project

It can also use MY_PI_WORKSPACE_ROOT. If neither is present, the server refuses to start unless the caller explicitly opts into the current directory with --allow-cwd.

This changes the initial contract. The agent is not silently granted access to whichever directory happened to be the process working directory. The runtime has a root against which workspace paths are resolved and revalidated.

That is less convenient than starting a shell in an arbitrary directory. It is also easier to inspect and explain.

Explicit authority does not make the host trustworthy by magic. The process still has the operating-system permissions of its account. The benefit is narrower: the repository boundary is part of the server configuration instead of an assumption shared only by the caller and the model.

Read-only is a useful state, not a broken state

The default my-pi profile is read-only. A normal session can inspect workspace metadata, read bounded file windows, search, query AST structure, request code-intelligence operations when their backends are available, and inspect Git status or diffs.

Mutation and language-server process startup require an explicit trusted profile:

my-pi-mcp \
--workspace /path/to/your/project \
--security-profile trusted

The distinction is useful even before making a security argument. Review, triage, code explanation, and repository exploration often do not require writes. A read-only session gives those tasks a meaningful operating mode instead of forcing every caller to choose between a full shell and no repository context.

The word “trusted” is deliberate. It describes an explicit authority decision about the workspace. It is not a universal security guarantee. The security model still matters, as do the host process, dependencies, operating-system permissions, and the code being inspected.

A small surface can be more legible than a large one

The stable alpha surface advertises 13 core tools:

workspace_info
fs_read, fs_write, fs_patch, fs_stat
search
ast_search
lsp_status, lsp_symbols, lsp_navigate, lsp_diagnostics
vcs_status, vcs_diff

The server also reports capability availability. That detail is important: discoverable does not mean that every backend is active in every environment. AST and LSP operations depend on their language tooling and runtime dependencies, while the filesystem, search, and VCS paths have a different set of requirements.

The point of listing the tools is not to claim that 13 is the perfect number. It is to make the interface inspectable. A caller can reason about the categories, their risk class, and their failure modes without first learning every command that a shell might launch.

The implementation is also not pretending that the underlying ecosystem disappears. For example, a VCS backend may use Git for read-only repository operations. The boundary under discussion is the authority exposed to the agent, not a promise that every internal dependency is rewritten from scratch.

Filesystem access is necessary, but it is not code intelligence

A repository is more than a tree of text files. A coding agent may need to answer questions such as:

Where is this function defined?
Which files reference this symbol?
Which implementation matches this structure?
What diagnostics does the language server report?
What changed relative to the current Git revision?

Shell commands can reconstruct many of those answers. my-pi exposes a few higher-level categories directly.

ast_search is intended for structure-aware search through supported languages. LSP tools provide status, diagnostics, symbols, and navigation when a compatible language server is available. Git tools provide bounded status and diff context.

This separation does not make a model understand code automatically. It does make the requested operation more explicit. “Find a function-shaped node” and “find a string in every file” are different questions, even if a shell can be used to approximate both.

The availability boundary is part of the contract. A tool that cannot run because a language server is absent should be reported as unavailable, not presented as if a successful semantic result had been produced.

Mutation should acknowledge stale context

One ordinary failure mode in agentic coding is stale state.

An agent reads a file, reasons about a change, and writes several seconds later. In the meantime, the file may have changed because of another agent, the developer, a formatter, or an earlier tool call. Blind overwrite semantics turn old reasoning into a silent lost update.

my-pi uses content preconditions for filesystem mutation. A read produces a content hash. An overwrite or patch carries the hash that the caller observed. The runtime compares it with the current file before publishing the change.

Conceptually:

read file
|
receive fingerprint
|
reason about change
|
write or patch with expected_hash
|
accept if the state matches
reject if the state is stale

For an existing file, fs_write requires expected_hash. fs_patch requires it as well. A missing or mismatched precondition fails before the mutation is committed. This is a small compare-and-swap style primitive, not a complete solution to concurrent development.

It does not prevent two agents from making incompatible edits when they both start from the same version. It does prevent the second writer from silently overwriting a version it never observed.

Sensitive paths should be policy decisions, not prompt suggestions

The runtime has a sensitive-path policy covering patterns such as .env*, .aws/, .ssh/, credential-like files, and key material. The policy is evaluated before a file is read or traversed into by the relevant capability.

That is a different boundary from telling a model:

Please do not read secrets.

Prompt guidance can influence behavior. It is not enforcement. A runtime policy can reject a path before its content is allocated into the tool result and model context.

This still requires honest scope. Sensitive-path matching is not a proof that every secret has a conventional filename. It is one policy layer in a local runtime. A user who changes the policy, grants trusted access, or runs the host with excessive operating-system privileges can change the practical risk.

The strongest case for unrestricted shell access

The best argument against a bounded interface is not that it is difficult to implement. It is that the shell already solves the general problem.

A shell is:

universal;
composable;
familiar to developers;
capable of invoking any compiler, linter, test runner, package manager, or script;
easier to extend than a fixed tool catalog.

Many coding agents are already good at shell use. Giving them a new capability protocol introduces schemas, error mapping, maintenance, and compatibility work. A narrow interface earns its place only if its explicit boundaries create practical value that justifies this friction.

For my-pi, the proposed advantages are explicit workspace authority, a meaningful read-only profile, content-preconditioned mutation, pre-read sensitive-path policy, structural search, semantic navigation, and bounded Git context.

Whether those advantages are enough is an empirical question. The answer will depend on the workflow. An agent that must run a custom build graph, invoke a database migration, debug a live process, or use an unfamiliar repository script may reasonably reach for a shell immediately.

Where this model is deliberately weaker

my-pi does not expose arbitrary command execution as one of its core repository tools. That means it is a poor fit for some tasks:

running tests with project-specific orchestration;
invoking build scripts and package managers;
starting or inspecting databases;
using dynamic debuggers;
operating deployment tools;
composing one-off repository automation;
investigating a system whose important state lives outside the workspace.

Those are not edge cases in software development. They are part of the reason the shell remains attractive.

The bounded model is therefore not “better than the shell” in the abstract. It is a candidate interface for a subset of repository work. Its success depends on whether that subset is large enough to justify a separate contract and whether the missing operations can be added without recreating arbitrary execution through a growing collection of escape hatches.

What my-pi does not claim

It does not claim that a bounded MCP surface is automatically secure.

It does not claim that shell access is always wrong.

It does not claim that the current alpha replaces a full coding environment.

It does not claim that tool count is a proxy for usefulness. Thirteen poorly designed tools would be worse than a shell; one missing operation can make an otherwise sensible workflow frustrating.

The project is a test of a design boundary. The repository contains the implementation, compatibility notes, and security model so that the claims can be challenged against code rather than treated as product copy.

What I want to learn

I am interested in concrete counterexamples and failures:

Which repository operation is missing before this interface becomes useful to you?
Which tool is redundant because an existing shell workflow is clearer?
Does content-preconditioned mutation prevent real failures in long-running or multi-agent sessions?
Is read-only code intelligence valuable on its own?
At what point does a bounded surface become more friction than simply giving the agent a terminal?

If the strongest answer is “the shell is already the right abstraction,” that is useful evidence. If a narrower surface is sufficient for a meaningful class of workflows, that is useful evidence too.

The goal is to test the trade-off rather than assume the answer.

Conclusion

General-purpose shell access is an extraordinarily powerful interface for coding agents. That is precisely why it is worth asking what should be exposed by default.

my-pi explores one alternative: an explicit workspace boundary with repository-specific filesystem, code-intelligence, mutation, and Git capabilities exposed through MCP. The design is early, intentionally narrow, and dependent on the environment in which it runs.

The useful question is not whether bounded access defeats shell access. It is where the boundary should sit for a real workflow.

What task would make you immediately abandon this bounded capability model and reach for unrestricted shell access instead?

Repository: github.com/BoxBoxmari/my-pi

Disclosure: I maintain the open-source my-pi project discussed here. I built it partly to test the capability-boundary ideas in this article.

DEV Community: Vương Nguyên Khang