How does Atlas detect a hanging `npm` command in a Three.js project?

Atlas's `bash` tool runs commands with a timeout. If the command exceeds this timeout, Atlas inspects its state and `shell_metadata` to determine if it was genuinely slow or blocked on interactive input, which is common in `npm` scripts within Three.js development.

Can Atlas help debug a slow `vitest` run in my Three.js application?

Yes, run `vitest` through `atlas bash`. If it's genuinely slow, Atlas will suggest increasing the timeout. If it's blocked, Atlas will identify the interactive input, allowing you to add non-interactive flags to your `vitest` command.

What if my Three.js build script is prompting for input and hanging?

Atlas will report that the command is blocked on interactive input within its `shell_metadata`. You should then re-run the command with appropriate non-interactive flags, such as `--no-input` or `-y`, within `atlas bash` to unblock it.

How do I increase the timeout for a long-running Three.js shader compilation?

Use `atlas bash --timeout "your-shader-compile-command"`. For example, `atlas bash --timeout 120000 "npm run compile-shaders"` would allow the command up to 2 minutes to complete, accommodating complex Three.js shader builds.

Does Atlas modify my Three.js code without my permission?

No. Atlas drafts plans in a read-only agent, asks for permission before running tools, and presents a unified diff for every proposed file edit (e.g., to `src/scene.js` or `package.json`) for your explicit approval before writing any changes.

How does Atlas know about my Three.js scene graph and materials?

Atlas indexes code by AST declarations using tree-sitter, allowing it to read your scene graph setup, render loop, materials, and GLSL shader strings. This provides the necessary context for Three.js-specific tasks like adding `dispose` paths or optimizing `Vector3` instances.

What if I manually stop a command running through Atlas?

If you abort a command yourself, Atlas's `shell_metadata` will explicitly state 'User aborted the command'. This clearly distinguishes your manual interruption from a command that timed out or was blocked, providing accurate context for your Three.js workflow.

Diagnose a hanging or long-running command in Three.js with Atlas in 2026

Atlas helps Three.js developers in 2026 quickly diagnose whether a `npm` script, `vitest` run, or custom build command is genuinely slow or silently blocked on interactive input, providing clear guidance to get it unstuck. By running your commands through Atlas's `bash` tool, you receive explicit `shell_metadata` that pinpoints the exact cause, allowing you to apply specific fixes like non-interactive flags or increased timeouts.

How Atlas Diagnoses Hanging `npm` or `vitest` Commands in Three.js Projects

Atlas's `bash` tool is designed to race every command against a timeout, providing a definitive diagnosis for hanging `npm` or `vitest` processes in your Three.js projects by 2026. When a command exceeds its allocated time, Atlas doesn't just kill it; it analyzes the state and provides a clear `shell_metadata` block.

When you execute a command like `npm install` or `vitest run` within your Three.js project using `atlas bash "npm install"`, Atlas monitors its execution. If the command fails to complete within the default or specified timeout, Atlas generates a `shell_metadata` block in its output. This metadata is crucial because it explicitly distinguishes between two common scenarios: a command that is genuinely taking a long time to execute (e.g., compiling complex GLSL shaders or running an extensive suite of Three.js tests) and one that is silently blocked, waiting for interactive input. This precise diagnosis prevents wasted time spent waiting for a command that will never resolve itself, a common frustration for developers working with large Three.js codebases and their associated build tools.

Identifying Blocked Interactive Input in Three.js Tooling with Atlas

Atlas explicitly calls out commands that are blocked on interactive input, a frequent cause of 'hanging' in Three.js development workflows by 2026. This clear identification in the `shell_metadata` block is a key feature, preventing you from mistakenly increasing timeouts for commands that are simply waiting for a 'yes' or 'no' response.

One of the most common reasons a command appears to hang is that it's silently waiting for user input on `stdin`. This can happen with `npm` scripts that prompt for configuration, or even certain `vitest` setups that might ask for confirmation before proceeding. When Atlas's `bash` tool detects this state, the `shell_metadata` output will contain a message explicitly stating that the command is blocked on interactive input. For example, if you run `atlas bash "npm init three-app"` and it prompts for project details, Atlas will report this blockage. This immediate feedback is invaluable for Three.js developers, as it directs them to the correct solution rather than a trial-and-error approach of adjusting timeouts.

Resolving Blocked Three.js Commands: Non-Interactive Flags and Atlas

Once Atlas identifies a Three.js-related command as blocked on interactive input, the solution is straightforward: re-run it with non-interactive flags, a practical approach in 2026. Atlas empowers you to quickly apply these flags, such as `-y`, `--no-input`, or enabling CI mode, directly through its `bash` tool.

If Atlas's `shell_metadata` indicates that your `npm` command, `vitest` setup, or custom build script is blocked on `stdin`, the next step is to re-execute it with flags that prevent it from prompting for input. Common flags include `-y` (for 'yes' to all prompts), `--no-input`, or setting environment variables that trigger a 'CI' (Continuous Integration) mode. For instance, if `npm install` is prompting for something, you would use `atlas bash "npm install --no-input"`. This ensures that your Three.js project's dependencies can be installed or its tests run without manual intervention, streamlining automated builds and local development alike. Atlas's ability to execute these modified commands directly makes the unblocking process efficient and transparent.

Handling Genuinely Slow Three.js Builds and Tests with Atlas Timeouts

For Three.js commands that are genuinely slow, such as extensive shader compilation or large `vitest` suites, Atlas provides a clear path to resolution by allowing you to increase the timeout value, a necessary adjustment in 2026. The `shell_metadata` will indicate a timeout without mentioning interactive input, guiding your next action.

Not all long-running commands are blocked; some simply require more time. In complex Three.js applications, tasks like compiling intricate GLSL shaders, optimizing large geometry assets, or running a comprehensive suite of `vitest` unit and integration tests can legitimately take several minutes. If Atlas's `shell_metadata` reports that a command timed out but does not mention being blocked on interactive input, it means the command was genuinely slow. In this scenario, Atlas's message will instruct you to retry with a larger timeout value. You can easily do this by specifying the timeout in milliseconds: for example, `atlas bash --timeout 120000 "vitest run"` would allow the `vitest` command up to 2 minutes to complete, accommodating the demands of modern Three.js development.

Reviewing Atlas's Actions and Diffing Changes in Three.js Codebases

Atlas prioritizes safety and transparency in 2026, ensuring that any proposed changes to your Three.js codebase, such as adding `dispose` paths or optimizing `Vector3` instances, are permission-gated and fully reviewable. Every file edit is presented as a unified diff for your explicit approval before it's written.

When Atlas operates on your Three.js project, its actions are always under your control. Before any tool call runs, it's permission-gated against allow, ask, and deny rules. For instance, if you ask Atlas to add a `dispose` path for geometries and materials in `src/scene.js` to prevent GPU memory leaks, Atlas will first draft a plan in a read-only agent. Once a plan is approved, and Atlas is ready to make changes, it computes a unified diff for every file edit. This diff is surfaced for your approval, allowing you to inspect precisely what changes Atlas proposes to files like `src/materials.js` or `package.json` before they are committed. This granular control ensures that Atlas enhances your Three.js development workflow without unexpected modifications, maintaining the integrity of your project and allowing you to stage and create commits on your behalf.

Step by step

01Run your potentially hanging Three.js-related command, such as `npm run build-scene` or `vitest run`, through Atlas using `atlas bash "npm run build-scene"`.
02Examine the `shell_metadata` block in Atlas's output when the command is killed or completes, looking for the diagnosis.
03If the `shell_metadata` explicitly states the command is blocked on interactive input, re-run it with non-interactive flags, for example: `atlas bash "npm install --no-input"` or `atlas bash "npm run setup-project -y"`.
04If the `shell_metadata` indicates a timeout without mentioning interactive input, retry the command with a larger timeout value in milliseconds, as instructed: `atlas bash --timeout 90000 "vitest run"` (for 90 seconds).
05If you manually aborted the command, confirm the `shell_metadata` says 'User aborted the command', distinguishing your interrupt from a timeout.
06If Atlas proposes code changes (e.g., to add `dispose` methods in `src/scene.js`), review the unified diff presented for approval before writing.

Frequently asked questions

How does Atlas detect a hanging `npm` command in a Three.js project?: Atlas's `bash` tool runs commands with a timeout. If the command exceeds this timeout, Atlas inspects its state and `shell_metadata` to determine if it was genuinely slow or blocked on interactive input, which is common in `npm` scripts within Three.js development.
Can Atlas help debug a slow `vitest` run in my Three.js application?: Yes, run `vitest` through `atlas bash`. If it's genuinely slow, Atlas will suggest increasing the timeout. If it's blocked, Atlas will identify the interactive input, allowing you to add non-interactive flags to your `vitest` command.
What if my Three.js build script is prompting for input and hanging?: Atlas will report that the command is blocked on interactive input within its `shell_metadata`. You should then re-run the command with appropriate non-interactive flags, such as `--no-input` or `-y`, within `atlas bash` to unblock it.
How do I increase the timeout for a long-running Three.js shader compilation?: Use `atlas bash --timeout <milliseconds> "your-shader-compile-command"`. For example, `atlas bash --timeout 120000 "npm run compile-shaders"` would allow the command up to 2 minutes to complete, accommodating complex Three.js shader builds.
Does Atlas modify my Three.js code without my permission?: No. Atlas drafts plans in a read-only agent, asks for permission before running tools, and presents a unified diff for every proposed file edit (e.g., to `src/scene.js` or `package.json`) for your explicit approval before writing any changes.
How does Atlas know about my Three.js scene graph and materials?: Atlas indexes code by AST declarations using tree-sitter, allowing it to read your scene graph setup, render loop, materials, and GLSL shader strings. This provides the necessary context for Three.js-specific tasks like adding `dispose` paths or optimizing `Vector3` instances.
What if I manually stop a command running through Atlas?: If you abort a command yourself, Atlas's `shell_metadata` will explicitly state 'User aborted the command'. This clearly distinguishes your manual interruption from a command that timed out or was blocked, providing accurate context for your Three.js workflow.

Try Atlas in your terminal

The terminal-native AI coding agent. Free core, single binary.

Install Atlas

Related guides

Diagnose a Hanging or Long-Running Command with Atlas in 2026

How to diagnose a hanging command with Atlas in 2026: the bash tool races every command against a timeout and tells you whether it is slow or blocked on input.

Atlas for Three.js: Terminal-Native AI Coding for Scenes, Materials, and Disposal in 2026

Atlas is a terminal-native AI coding agent for Three.js in 2026, where geometry, material, and texture disposal is the difference between a demo and a leak.

Rename a symbol across the repo in Three.js with Atlas in 2026

Refactor Three.js code with Atlas in 2026. Rename functions, classes, or constants across your entire repository, ensuring all references are updated, including those missed by `grep` alone. Atlas uses `lsp`, `grep`

Onboard to an Unfamiliar Three.js Codebase with Atlas in 2026

Quickly build a mental model of any Three.js repository in 2026 using Atlas. Leverage semantic search, file globbing, and read-only exploration to understand scene graphs, materials, and render loops without reading

Run Atlas Headless in CI for Three.js Projects in 2026

Automate Three.js code improvements in CI with Atlas. Run Atlas headless to fix memory leaks and optimize render loops, getting machine-readable output for vitest and prettier.

Trace a runtime bug from a stack trace in Three.js with Atlas in 2026

Pinpoint Three.js runtime bugs from production stack traces using Atlas in 2026. Go from a file:line error to a fix and regression test, all without attaching a debugger.

Extract a Shared Helper from Duplicated Code in Three.js with Atlas in 2026

Refactor your Three.js codebase in 2026 by extracting duplicated logic into a single, tested helper using Atlas. Prevent GPU memory leaks and improve performance.

Refactor a legacy Three.js module with Atlas in 2026

Safely refactor legacy Three.js modules in 2026 with Atlas. Map callsites, pin behavior with vitest, apply changes with apply_patch, and ensure no regressions.

Browse this resource hub