Try free

Last updated 13 October 2026

Run a linter after a Claude Code task

Automating code quality checks after agent tasks

Claude Code works fast and modifies multiple files in a single session. While the agent is highly capable, it might occasionally leave behind small styling issues or unused variables that your project linter would normally catch. Manually running your linting suite after every interaction with the agent is tedious. It breaks your concentration and adds a repetitive step to your development cycle. You want the agent to be responsible for the health of the code it writes without you having to prompt it every time.

When you use a command line agent, you expect a certain level of autonomy. If you have to type a lint command manually after the agent says it is finished, you are essentially babysitting the tool. This is especially frustrating in large projects where linting takes more than a few seconds. By the time you see the errors, you have already moved on to the next task. Integrating the linter directly into the agent workflow solves this by making code quality a background task that happens automatically.

Understanding the hook system for automation

Claude Code includes a powerful hook system that allows you to trigger specific actions at different stages of a session. These hooks are designed to help you integrate the agent into your existing build pipelines and developer tools. For the specific goal of post-task linting, the Stop event is the most relevant trigger. This event occurs every time the agent completes a task and returns to an idle state where it waits for your next instruction. It is the perfect moment to verify that the changes just made conform to your project standards.

There are other hook events available such as SessionStart and SessionEnd, but these are less useful for immediate feedback on code changes. The Stop event ensures that every time the agent finishes using the Bash tool or the Edit tool to modify your files, the linter runs immediately. This provides a tight feedback loop. If the linter finds an issue, the output is visible in your terminal right away. You can then immediately ask the agent to fix the errors it discovered before you commit the code.

Configuring the settings file for hooks

To set up your automatic linter, you must modify the configuration files that Claude Code reads. The primary location for project specific settings is the .claude/settings.json file in your project root. If this file does not exist, you can create it. This file uses a standard JSON format to define how the agent behaves within that specific repository. You can also use the /config slash command inside a session to view your current settings and see where the agent is pulling its instructions from.

Inside the settings.json file, you will define a hooks section. This section maps specific hook events to the commands you want to run. You must specify the Stop event and provide the exact shell command that initiates your linter. Because Claude Code uses the Bash tool to execute these commands, you can use any command that works in your standard terminal. This includes running scripts defined in your project configuration or calling global binaries like Ruff or ESLint directly.

Defining the linting command in JSON

The command you write in the Stop hook should be concise and effective. For a project using Node.js, you might set the command to run a lint script. For a Python project, you might call a specific linting tool on the current directory. It is important to ensure that the command you choose is available in the environment where you run the agent. If the command fails because a dependency is missing, the agent will report a hook execution error in the terminal, which can be distracting.

You should also consider the scope of the linting. Running a full project lint on a massive codebase after every small change can be slow. If your linting tool supports checking only modified files, that is often a better choice for a hook. This keeps the agent responsive. You do not want to wait thirty seconds for a linter to finish every time the agent edits a single line of code. Speed is essential for maintaining the flow of an interactive coding session.

Monitoring multiple sessions with adhdTerminal

When you start automating tasks across multiple projects, keeping track of every active session becomes a challenge. You might have one instance of the agent refactoring a library while another is updating a front-end component. If both are running post-task hooks, your terminal can become a wall of scrolling text. This is an area where adhdTerminal is the honest answer for managing complexity. It allows you to run many Claude Code sessions side by side as tiles on a single dashboard.

Each tile in adhdTerminal shows the status of the session, such as whether it is working or waiting for you. When a post-task hook runs, you can see the results in the tile without switching tabs. This is particularly helpful if a linter fails in a background session while you are busy in another. The tile system ensures that you never lose track of which project needs attention. You can monitor the health of your entire workspace from one screen, making automated hooks much more manageable.

Setting global versus local hooks

If you find yourself adding the same linting hook to every project, you might prefer to use a global configuration. Claude Code reads global settings from ~/.claude/settings.json on your computer. Adding a hook here applies it to every session you start, regardless of the folder you are in. This is useful for general purpose tools like code formatters or security scanners that you want active at all times. It ensures a consistent development environment across all your work.

However, local settings in the .claude/settings.json file of a project will always take precedence or complement these global rules. Local settings are usually better for linting because linting rules are often highly specific to a project. A global hook might fail if it tries to run a command that a specific project does not support. It is usually best to keep global hooks limited to tools that are truly universal and use project specific settings for anything that depends on the local environment or language.

Verifying the setup with internal tools

Once you have configured your hooks, you should verify that everything is working as expected. You can run the claude doctor command in your terminal to check the status of your installation and your configuration files. This command will alert you if your settings.json file has syntax errors that prevent the agent from loading your hooks. It is a quick way to ensure that your automation is actually active before you start a long coding session.

Inside an active session, you can also use the /hooks slash command. This command provides a summary of all active hooks and tells you which commands are mapped to which events. If you notice that your linter is not running, the /hooks command will help you identify if the event is being ignored or if the command path is incorrect. This internal transparency makes it much easier to debug your automation scripts without leaving the agent interface.

Improving agent behavior with CLAUDE.md

Running the linter is only half the battle; the agent also needs to know what to do when the linter fails. You can use the CLAUDE.md file in your project root to provide context. In this file, you can add instructions that tell the agent to always check the output of the Stop hook. You can instruct the agent that if it sees linting errors in the terminal after it finishes a task, it should automatically attempt to fix them using the Edit tool.

Because the agent has access to the full conversation history and terminal output, it can see the specific line numbers and error messages produced by your linter. If your instructions in CLAUDE.md are clear, the agent becomes self-correcting. It will run the task, see the linter fail in the hook, and then immediately start a new turn to fix the style issues. This creates a truly autonomous workflow where you only receive code that has already passed all your local quality gates.

Managing performance and context limits

Every time a hook runs and prints output to the terminal, that output becomes part of the session context. If your linter produces thousands of lines of warnings, it can quickly fill up the context window. This might lead to higher costs or require you to use the /compact command more frequently. To avoid this, try to configure your linter to be quiet or only show errors. This keeps the conversation history clean and focused on the actual code logic.

If the context does get too large, remember that the /compact command will summarize the session and free up space. You can even use the PreCompact hook to perform specific cleanup before this happens. By balancing the frequency of your hooks with the size of their output, you maintain a fast and efficient environment. This allows you to reap the benefits of automation without the downside of a bloated session history that slows down the agent response time.

Questions people ask

How can I stop a long-running linting hook if it gets stuck?

You can press the Escape key once to interrupt the current operation of the agent, including any command running via a hook. If the hook is totally unresponsive, pressing Ctrl+C will quit the entire Claude Code session. After restarting with the claude --continue command, you can investigate why the command hung by checking your local environment.

Can I use multiple commands in a single hook event?

Yes, because the hook executes as a shell command through the Bash tool, you can chain commands together using standard shell syntax like double ampersands. This allows you to run a formatter first and then a linter immediately after. Just ensure the combined string is correctly formatted within the .claude/settings.json file.

Will my hooks run when I use the -p flag for a single prompt?

Yes, hooks like Stop will still trigger even when running a single prompt with the -p flag. The agent executes the prompt, finishes the task, and then fires the hook event before it prints the final answer and exits. This ensures that even one-off changes are subjected to your automated quality checks.

Read next

More on claude code basics·All posts