How do I debug a hanging `forge test` in Atlas?

Run `forge test` through Atlas's `bash` tool. If it hangs, Atlas's `shell_metadata` will tell you if it is genuinely slow or blocked on interactive input, guiding you to either increase the timeout or use non-interactive flags.

What happens if my Solidity build is just very slow, not blocked?

If your Solidity build, such as a complex `forge test` run, is genuinely slow, Atlas's `shell_metadata` will indicate a timeout without an interactive input block. Atlas will then instruct you to retry the command with a larger timeout value in milliseconds.

How does Atlas ensure safety when modifying Solidity code?

Atlas ensures safety by permission-gating every tool call, drafting plans in a read-only agent, and presenting a unified diff for every file edit, such as changes to `src/MyContract.sol` or `foundry.toml`, for your explicit approval before writing.

Does Atlas understand my Foundry project structure?

Yes, Atlas is designed to work within a Foundry project, reading `foundry.toml`, `src/` directories, and understanding Solidity contracts, storage layouts, and libraries installed by `forge soldeer`.

Can Atlas help with `forge fmt` if it hangs?

While `forge fmt` is typically fast, if it were to hang for an unexpected reason, Atlas's `bash` tool would diagnose it just like any other command, indicating if it's slow or blocked, and providing guidance to resolve the issue.

How does Atlas distinguish between my manual abort and a timeout?

If you manually abort a Solidity command running through Atlas, the `shell_metadata` block in the output will explicitly state 'User aborted the command,' clearly distinguishing your interrupt from a timeout initiated by Atlas.

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

In 2026, Solidity developers can quickly diagnose hanging or long-running commands like `forge test` or `forge soldeer install` by running them through Atlas's `bash` tool, which explicitly identifies if a process is genuinely slow or blocked on interactive input, providing clear steps to unblock it.

How does Atlas diagnose a hanging `forge test` in Solidity?

Atlas's `bash` tool, a core feature for Solidity developers in 2026, diagnoses hanging commands like `forge test` by racing every execution against a timeout. When a command exceeds this limit, Atlas provides precise `shell_metadata` that distinguishes between a genuinely slow process and one silently blocked on interactive input.

When a Solidity developer runs a command such as `forge test` to execute their smart contract tests within a Foundry project, Atlas wraps this execution with its `bash` tool. This tool is designed to monitor the command's progress and enforce a timeout. If `forge test`, or any other Solidity tool like `forge soldeer install`, fails to complete within the specified duration, Atlas does not simply report a generic timeout. Instead, it generates a detailed `shell_metadata` block in its output. This metadata explicitly states whether the command was killed because it was genuinely taking too long, or crucially, if it was blocked waiting for interactive input. This distinction is vital for Solidity developers, as a `forge test` might be slow due to extensive fuzzing, while `forge soldeer install` might be waiting for a 'yes/no' confirmation. Atlas indexes code by AST declarations using tree-sitter, not blind line windows, giving it a deeper understanding of the Solidity codebase, including `src/MyContract.sol` and `test/MyTest.t.sol` files, even when diagnosing execution issues.

What Solidity commands does Atlas monitor for hangs?

Atlas's `bash` tool monitors critical Solidity commands such as `forge test`, `forge soldeer install`, and `forge fmt` for hanging or long-running behavior. This capability ensures that developers working in a Foundry project in 2026 receive immediate diagnostic feedback for their core toolchain operations.

Atlas provides comprehensive monitoring for the entire Solidity toolchain within a Foundry project. This includes the test runner `forge test`, the package manager `soldeer` (specifically `forge soldeer install`), and the formatter `forge fmt`. When a developer initiates any of these commands through Atlas, the `bash` tool actively tracks their execution. For instance, if `forge soldeer install` is used to manage dependencies defined in `foundry.toml` and it hangs, Atlas will intervene. Similarly, a `forge test` run that takes an unexpectedly long time, perhaps due to complex contract interactions or extensive fuzzing, will be diagnosed. Even `forge fmt`, though typically fast for `src/MyContract.sol` files, would be subject to this diagnostic process if it were to hang. Atlas's terminal-native TUI, rendered with SolidJS through the OpenTUI renderer, presents this diagnostic information clearly, allowing Solidity developers to quickly understand the state of their build or script and take corrective action. Atlas connects to Model Context Protocol servers and exposes their tools to the agent, ensuring direct integration with the Solidity ecosystem.

How does Atlas help unblock interactive Solidity commands?

When Atlas detects that a Solidity command, such as `forge soldeer install`, is blocked on interactive input, it explicitly highlights this in the `shell_metadata` block. This clear diagnosis, a key feature for developers in 2026, guides users to re-run the command with non-interactive flags to unblock it.

One of the most common causes of 'hanging' commands in automated environments or scripts is a silent wait for interactive input. Atlas's `bash` tool is specifically designed to identify this scenario for Solidity commands. If `forge soldeer install` attempts to prompt the user for a 'yes/no' confirmation and no input is provided, Atlas will kill the command after its timeout and, crucially, report in the `shell_metadata` that the command was blocked on interactive input. This explicit message prevents developers from wasting time waiting for a command that will never resolve itself. Atlas then instructs the user to re-run the command with appropriate non-interactive flags, such as `-y` or `--no-input`, or to enable a CI mode if the tool supports it. This proactive guidance ensures that Solidity developers can quickly get their `forge soldeer install` or other interactive commands unstuck, maintaining workflow efficiency within their Foundry projects. Atlas drafts a plan in a read-only plan agent and asks before switching to a build agent, ensuring transparency in its suggestions.

How does Atlas manage genuinely slow Solidity operations?

For Solidity commands that are genuinely slow, like a comprehensive `forge test` run, Atlas's `shell_metadata` indicates a timeout without an interactive input block. Atlas then instructs the developer to retry the command with a larger timeout value in milliseconds, providing precise control over execution limits in 2026.

Not all long-running commands are blocked; some Solidity operations are simply computationally intensive. A `forge test` run with extensive fuzzing, or a `forge snapshot` operation on a large codebase, can genuinely take a significant amount of time. When such a command exceeds Atlas's default timeout, the `shell_metadata` will clearly state that the command was killed due to a timeout but will not mention interactive input. In these cases, Atlas provides actionable advice: retry the command with a larger timeout value, specified in milliseconds. This allows Solidity developers to fine-tune the execution limits for their specific needs, ensuring that complex but valid operations are not prematurely terminated. Atlas also supports a robust review process; it computes a unified diff for every file edit and surfaces it for approval before writing. This is particularly important in Solidity development, where every diff has a gas cost and an attack surface, allowing developers to review changes to `src/MyContract.sol` or `test/MyTest.t.sol` before committing.

What safety and review mechanisms does Atlas offer for Solidity developers?

Atlas provides robust safety and review mechanisms for Solidity developers, including permission-gated tool calls and unified diffs for every file edit. This ensures that all changes, from `forge fmt` to contract modifications, are transparent and approved, crucial for smart contract security in 2026.

Working with Solidity smart contracts demands stringent safety and review processes, given that every diff has a gas cost and an attack surface. Atlas is built with these requirements in mind. Every Atlas tool call, whether it involves running `forge test`, managing dependencies with `forge soldeer install`, or formatting code with `forge fmt`, is permission-gated against allow, ask, and deny rules before it runs. This means a developer must explicitly approve actions that could modify their Solidity codebase. Furthermore, Atlas drafts a plan in a read-only plan agent and asks for approval before switching to a build agent, providing an additional layer of scrutiny. When Atlas proposes any file changes, such as adding a reentrancy guard to `src/MyContract.sol` or converting a `require` string to a custom error, it computes a unified diff for every file edit and surfaces it for approval before writing. This allows Solidity developers to meticulously review the exact changes, even running `forge snapshot` to see the gas delta before approving. Atlas also reads git branches, status, and diffs, and can stage and create commits on your behalf, integrating direct into a secure Solidity development workflow.

Step by step

01Run your potentially hanging Solidity command, such as `forge test` or `forge soldeer install`, through Atlas's `bash` tool.
02Examine the `shell_metadata` block in Atlas's output if the command is killed, looking for explicit mentions of 'interactive-input' or 'timeout'.
03If Atlas indicates the Solidity command is blocked on interactive input (e.g., `forge soldeer install` waiting for confirmation), re-run it with non-interactive flags like `-y` or `--no-input`.
04If Atlas reports the Solidity command is genuinely slow (e.g., a long `forge test` run) and killed by timeout, retry the command with a larger timeout value in milliseconds as instructed by the `shell_metadata`.
05Review any proposed file changes, such as those from `forge fmt` or a contract modification in `src/`, by inspecting the unified diff Atlas presents for approval.
06If you manually aborted a Solidity command, confirm the `shell_metadata` states 'User aborted the command' to distinguish your interrupt from an Atlas timeout.

Frequently asked questions

How do I debug a hanging `forge test` in Atlas?: Run `forge test` through Atlas's `bash` tool. If it hangs, Atlas's `shell_metadata` will tell you if it is genuinely slow or blocked on interactive input, guiding you to either increase the timeout or use non-interactive flags.
Can Atlas detect if `forge soldeer install` is waiting for input?: Yes, Atlas's `bash` tool explicitly calls out when a command like `forge soldeer install` is blocked on interactive input, allowing you to re-run it with flags like `-y` or `--no-input` to unblock it.
What happens if my Solidity build is just very slow, not blocked?: If your Solidity build, such as a complex `forge test` run, is genuinely slow, Atlas's `shell_metadata` will indicate a timeout without an interactive input block. Atlas will then instruct you to retry the command with a larger timeout value in milliseconds.
How does Atlas ensure safety when modifying Solidity code?: Atlas ensures safety by permission-gating every tool call, drafting plans in a read-only agent, and presenting a unified diff for every file edit, such as changes to `src/MyContract.sol` or `foundry.toml`, for your explicit approval before writing.
Does Atlas understand my Foundry project structure?: Yes, Atlas is designed to work within a Foundry project, reading `foundry.toml`, `src/` directories, and understanding Solidity contracts, storage layouts, and libraries installed by `forge soldeer`.
Can Atlas help with `forge fmt` if it hangs?: While `forge fmt` is typically fast, if it were to hang for an unexpected reason, Atlas's `bash` tool would diagnose it just like any other command, indicating if it's slow or blocked, and providing guidance to resolve the issue.
How does Atlas distinguish between my manual abort and a timeout?: If you manually abort a Solidity command running through Atlas, the `shell_metadata` block in the output will explicitly state 'User aborted the command,' clearly distinguishing your interrupt from a timeout initiated by Atlas.

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.

Onboard to an Unfamiliar Solidity Codebase with Atlas in 2026

Solidity developers in 2026 can rapidly build a mental model of any unfamiliar codebase using Atlas. Leverage semantic search, AST indexing, and Foundry toolchain integration with forge test, soldeer, and forge fmt.

Automate GitHub Issue and Pull Request Triage in Solidity with Atlas in 2026

Automate GitHub issue and pull request triage for Solidity projects using Atlas. Safely respond to PRs and issues in 2026, ensuring trusted users and proper context handling with Foundry.

Document a module with a README in Solidity with Atlas in 2026

In 2026, Atlas helps Solidity developers generate accurate READMEs for smart contracts. It uses `forge test`, `soldeer`, and `forge fmt` to reflect current code behavior.

Audit a Solidity Repo with Parallel Subagents in Atlas, 2026

Sweep your Solidity repository for common problems using Atlas's parallel subagents. Identify issues in Foundry projects without blowing your context window, ensuring secure smart contracts.

Write Unit Tests for Untested Solidity Code with Atlas in 2026

Add robust unit tests to your Solidity contracts using Atlas. Leverage `forge test`, `soldeer`, and `forge fmt` to ensure code quality and security in 2026.

Rename a symbol across the repo in Solidity with Atlas in 2026

Rename Solidity functions, classes, or constants across your entire repository with Atlas. Leverage precise LSP references and `forge test` verification for safe, accurate refactoring in 2026.

Locate Where a Behavior is Implemented in Solidity with Atlas in 2026

Discover how Atlas helps Solidity developers in 2026 pinpoint exact file and symbol implementations for contract behaviors using Foundry's toolchain, semantic search, and LSP.

Browse this resource hub