← Back to AI Insights
Gemini Executive Synthesis

strukto-ai/mirage `Workspace.execute` working directory handling

Technical Positioning
Granular and safe control over command execution context for AI agents
SaaS Insight & Market Implications
This feature request identifies a critical developer pain point in `Mirage`'s `Workspace.execute` API: the lack of a per-call `cwd` override. Current methods, such as mutating `session.cwd` or using `cd && cmd` prefixes, are either racy under concurrency, resource-intensive, or introduce command history pollution and quoting complexities. AI agent orchestrators frequently require executing commands in specific directories without altering the session's global state. The absence of a first-class `cwd` option forces developers into cumbersome workarounds, increasing complexity and potential for errors. For B2B SaaS platforms, this impacts the efficiency and reliability of agent workflows, underscoring the need for an API that aligns with standard execution paradigms like Node's `child_process`.
Proprietary Technical Taxonomy
per-call `cwd` override Workspace.execute sessionId agentId signal stdin provision native

Raw Developer Origin & Technical Request

Source Icon GitHub Issue May 7, 2026
Repo: strukto-ai/mirage
Feature: support per-call `cwd` in `ExecuteOptions`

## Summary

`Workspace.execute(command, options)` currently accepts `sessionId`, `agentId`, `signal`, `stdin`, `provision`, `native`, and `noHistory`, but no per-call `cwd` override. To run a command in a different working directory than the session's current `cwd`, callers have to mutate `session.cwd`, run, and restore — which is racy if two `execute()` calls overlap on the same session.

It would be very useful to support a per-call `cwd` directly:

```ts
await ws.execute('ls', { sessionId: 'agent-1', cwd: '/data' });
```

## Why this matters

Agent harnesses and orchestrators routinely need to run a command in a specific directory without permanently changing the session's `cwd`. Today the only safe pattern requires either:

1. Snapshot `session.cwd` → mutate → run → restore in `finally`. Works for serial use but breaks under any concurrency on the same session.
2. Spin up a disposable Mirage session per call, set its `cwd`, and dispose it. Works but is heavyweight, and loses any session-scoped state the caller wanted to share (env, history, function definitions).
3. Shell-prefix with `cd && cmd`. Works but is a workaround, polluting the recorded command history with `cd` noise and forcing every caller to do POSIX-safe path quoting.

A first-class `cwd` option would eliminate all three workarounds and make the API match common expectations from Node's `child_process` and similar libraries.

## Proposed shape

```ts
export interface ExecuteOptions {
// ...exi...

Developer Debate & Comments

No active discussions extracted for this entry yet.

Adjacent Repository Pain Points

Other highly discussed features and pain points extracted from strukto-ai/mirage.

Extracted Positioning
strukto-ai/mirage virtual filesystem performance (multi-file operations)
Optimized performance for multi-file operations, leveraging backend-specific batching
Extracted Positioning
strukto-ai/mirage `Workspace.execute` environment variable handling
Granular and safe control over execution environment for AI agents
Extracted Positioning
strukto-ai/mirage `Workspace.execute` command execution
Reliable command execution control and resource management via `AbortSignal`

Engagement Signals

0
Replies
open
Issue Status

Cross-Market Term Frequency

Quantifies the cross-market adoption of foundational terms like native and signal by tracking occurrence frequency across active SaaS architectures and enterprise developer debates.