Set Up Claude Code's Status Line

Set up a live Claude Code status line showing model, context, and cost.

Introduction

⚡️ 30 Second Summary

When you are deep in a coding session with Claude Code, it is easy to lose track of how much context you have used, how much the session has cost, and which model you are running.

In this project, you will set up a live status line in Claude Code that displays your current model name, context window usage percentage, and accumulated session cost directly in your terminal footer.

What You'll Build

A Node.js script that powers a real-time status line in Claude Code, showing the model, context usage, and cost at a glance.

By the end of this project, you'll have:

  • 📊 A working Claude Code status line showing model, context percentage, and cost in real time.
  • 📝 A Node.js status line script at ~/.claude/statusline.js, wired into settings.json.
  • 🧹 Practical habits for using /compact and /clear to manage context efficiently.
  • 💎 Secret Mission: Add color-coded context warnings with /compact and /clear advice.

Want a complete demo of how to do this project, from start to finish? Check out our 🎬 walkthrough with NextWork

Do I need to pay to do this project?

No direct cost. Claude Code requires a Claude Pro ($20/mo) or Claude Max ($100/mo) subscription, which you will need to do this project. Not sure? Ask in the Community, we'll help.

Not sure if this project is right for you? Check if it matches your goals

If you're up for a bit of a challenge, quiz yourself on the key concepts up ahead in this project.

Get Your Tools Ready

First, let's confirm Claude Code is installed and responding. Claude Code is the AI coding assistant that runs in your terminal, and it is the tool you will be customizing throughout this project.

In this step, get ready to:

  • Verify Claude Code is installed.
  • Run a test prompt to confirm it is working.

Check Your Claude Code Installation

🍎 macOS

  • Press Command + Space, type Terminal, and press Enter.
  • Run this command:

🖼️ Windows

  • Press the Windows key, type Terminal, and press Enter.
  • Run this command:
claude --version

What do you see? You should see a version number like 2.x.x.

✔️ I see a version number

You are all set. Claude Code is already installed and ready to go.

Minimum version

This project requires Claude Code version 2.0 or above. If your version is lower, run the install command in the other tab to update.

ⓧ Command not found

No worries! We'll need to install Claude Code first.

Off we go...

Install Claude Code

Claude Code is installed as a native binary, so it's a single command!

🍎 macOS / Linux

  • Open your terminal.
  • Copy & paste the following command:
curl -fsSL https://claude.ai/install.sh | bash
  • Press Enter.

🖼️ Windows

Claude Code on Windows requires Git Bash, which comes with Git for Windows. Let's check if you have it, then install Claude Code.

  • Open PowerShell and run:
git --version

If you see something like git version 2.x.x, you're good to go.

Already have Git?

If git --version printed a version, skip to the next step.

Install Git

  • Run the downloaded installer.
  • If you see a security warning, click Run.

Walk Through the Setup Wizard

The default settings are fine for most screens. Here's what you'll see:

  • Accept the license agreement and click Next.
  • Leave the destination as C:\Program Files\Git and click Next.
  • Leave the default components selected and click Next.
  • Leave the Start Menu folder as Git and click Next.
  • Leave the default editor setting and click Next.
  • Leave "Let Git decide" selected for the initial branch name and click Next.
  • On the "Adjusting your PATH environment" screen, make sure "Git from the command line and also from 3rd-party software" is selected. Click Next.
Why does the PATH setting matter?

This option lets you run git from PowerShell and other programs, not just Git Bash. Claude Code needs this to work correctly.

  • Leave "Use bundled OpenSSH" selected and click Next.
  • Leave the HTTPS transport backend setting and click Next.
  • Leave the terminal emulator setting and click Next.
  • Leave the default git pull behavior and click Next.
  • Leave "Git Credential Manager" selected and click Next.
  • Leave the extra options as-is and click Install.
  • Wait for the installation to finish.
  • Click Finish.
  • Verify Git Bash is installed by opening PowerShell and running:
git --version

You should see something like git version 2.x.x.

Install Claude Code

  • In the same PowerShell window, copy & paste the following command:
irm https://claude.ai/install.ps1 | iex
  • Press Enter.
What does this command do?

irm downloads the installer script and iex executes it. This installs Claude Code as a standalone program on your machine. Claude Code uses Git Bash under the hood to run commands, which is why Git for Windows is required. Read more in the official docs.

💡 Prefer WSL?

If you have Windows Subsystem for Linux (WSL) set up, you can install Claude Code inside WSL using the macOS/Linux command instead. WSL 2 also enables sandboxing for enhanced security.

  • Verify the installation by running:
claude --version

✔️ I see a version number

You should see something like claude 2.1.x. The exact version may differ. Claude Code is installed!

ⓧ Command not found

🍎 macOS / Linux

Did your installer show a Setup notes warning?

  • Run the following commands to fix it:
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
What does this command do?

The first line adds ~/.local/bin (where Claude Code lives) to your PATH permanently by writing it to your shell config file. The second line reloads the config so the change takes effect right away.

🙋‍♀️ Using bash instead of zsh?

Replace ~/.zshrc with ~/.bashrc in the commands above. Not sure which shell you're using? Run echo $SHELL to find out.

🖼️ Windows
  • Close your PowerShell window and open a new one. The installer updates your PATH, but existing terminals won't see the change until restarted.
  • If it still doesn't work, try running the installer again:
irm https://claude.ai/install.ps1 | iex
  • Verify the installation again by running:
claude --version
Still stuck?

Get help with your error or share your error with the NextWork community!

Set Up Your Claude Account

Claude Code needs a paid account to run. You can use either a Claude subscription or Anthropic API credits.

Why does Claude Code cost money?

Claude.ai (the chatbot) and Claude Code both use tokens to process your messages. The difference is how many tokens they use. A chatbot conversation is short and lightweight. Claude Code reads your entire project, writes full files, and runs commands, so it uses significantly more tokens per session. A paid account gives you the token budget Claude Code needs to do its job.

✔️ I already have one of these

You're all set! You'll connect Claude Code to your account in the next step.

🤔 Help me decide

There are two ways to pay for Claude Code:

Which option should I choose?

If you're new to Claude, start with a Pro subscription. You get Claude Code plus the Claude.ai chatbot, all in one plan.

If you only want to try Claude Code for this project, API credits let you pay for exactly what you use.

📋 Set up a Claude subscription

Claude Code works with a Claude Pro ($20/mo) or Max ($100/mo) subscription. Here's how to set one up:

  • Click Sign Up and create an account with your email or Google account.
  • Once logged in, click Upgrade in the center of the page.
  • Select the plan of your choice.
  • Choose either monthly or yearly billing.
  • Enter your payment details.

Your subscription gives you a monthly token allowance that covers Claude Code usage. Pro is plenty for this project.

🪙 Set up Anthropic API credits

Claude Code also works with pay-as-you-go API credits (~$6/day average). Here's how to set them up:

  • Go to console.anthropic.com in your browser.
  • Sign in, or create an account with your email or Google account.
  • Once logged in, select Buy credits in the center of the Claude Console.
  • Add credits to your account. $5-10 is more than enough for this project.
  • Click Add Payment Method.
  • Enter your payment details.
  • Go to API Keys in the left sidebar.
  • Click Create Key.
  • Give it a name (e.g., "claude-code").
  • Copy the key.
  • Save the key somewhere safe. You'll use it in the next step.
Free credits for new accounts

New Console accounts sometimes get $5 in free credits, enough to complete this entire project. Check your Billing page after signing up.

Test That Claude Code Responds

  • Run this command to confirm Claude Code responds to prompts:
claude "say hello"

What is the "trust this folder" prompt?

Claude Code runs a safety check the first time it accesses a workspace. Select Yes, I trust this folder and press Enter to continue. This is a one-time check per folder.

What do you see?

✔️ Claude responded

Nice work. Your Claude Code installation is confirmed and working.

ⓧ I see an error

That's okay! Let's troubleshoot:

  • Run /doctor inside Claude Code to check for issues.
  • Check that you have an active subscription (Claude Pro or Claude Max).
  • Make sure you are connected to the internet.
  • Try running claude without any arguments to start an interactive session, then type your prompt.
  • Try running the install command again.

Still stuck?

Get help with your error or share your error with the NextWork community!

Your tools are confirmed and working. Next up, you will customize Claude Code's status line to make it your own.

Set Up Your Status Line

You have confirmed that Claude Code is installed and responding. But right now, your terminal does not show you anything about your active session. You have no idea which model is running, how much context you have left, or what the session is costing you.

In this step, you will add a status line that fixes that. This is a live info bar at the bottom of your terminal that shows which model is active, how much context window you have left, and your session's cost.

In this step, get ready to:

  • Prompt Claude Code to generate a status line script.
  • Verify the status line appears in your terminal.

Prompt Claude Code to Create Your Status Line

  • If you still have Claude Code open from Step 1, you are ready to go. If not, open a new session by running claude in your terminal.
  • Paste the following prompt into Claude Code and press Enter:
Set up a Claude Code statusline from scratch. I don't have a statusline or PS1 configured yet.

Create a statusline.js script at ~/.claude/statusline.js that displays the following elements in order, separated by two spaces:

1. The literal text STATUSLINE ACTIVE (no color)
2. The Claude model name from data.model.display_name — in cyan
3. The current git branch from data.workspace.git_branch (if present) — in yellow
4. Context usage from data.context_window.used_percentage, formatted as ctx:XX% — in dim
5. Session cost from data.cost.total_cost_usd — in green (show in cents like $2.3¢ when under $0.10, otherwise dollars like $0.123)

The script should read JSON from stdin (Claude Code passes session data this way), parse it, and write the assembled statusline to stdout using ANSI escape codes for color. If JSON parsing fails, fall back to outputting just claude.

For reference, the JSON structure Claude Code passes looks like:
{
  "model": { "display_name": "..." },
  "workspace": { "git_branch": "..." },
  "context_window": { "used_percentage": 2 },
  "cost": { "total_cost_usd": 0.738 }
}

Then configure ~/.claude/settings.json to enable the statusline:
{
  "env": {
    "CLAUDE_CODE_ENABLE_STATUSLINE": "1"
  },
  "statusLine": {
    "type": "command",
    "command": "node /Users/<their-username>/.claude/statusline.js"
  }
}
Replace <their-username> with the actual username. Don't set CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS unless I ask.

What is this prompt doing?

This prompt creates two things that work together:

  • A Node.js script (statusline.js) that reads live session data (model name, context usage, git branch, and cost) from a JSON feed and formats it into a status line. This script is the code that decides what your status line looks like.
  • A settings update (settings.json) that tells Claude Code to run that script. Without this, Claude Code would not know the script exists. The settings file points to the script, and the script produces the output.

What does the JSON structure look like?

Claude Code will start generating your status line. Follow along as each prompt appears.

Seeing different prompts?

Claude Code updates regularly, so the exact prompts you see may look slightly different from what is shown here. Follow along as best you can, and if anything seems off, ask in the Community.

  • Claude Code creates the script file first.
  • You will see: Do you want to create statusline.js? Select Yes.
  • Next, Claude Code updates your settings file.
  • You will see: Do you want to make this edit to settings.json? Select Yes.

What does "Yes, and allow Claude to edit its own settings" mean?

This option lets Claude Code skip the permission prompt for future settings changes during this session. It is safe to choose either Yes or this option. If you are unsure, just choose Yes.

  • Claude Code may also test the script to make sure it works.
  • You will see: Do you want to proceed? Select Yes.
  • Once Claude Code has finished running, it will tell you to type /exit and then run claude to see the status line in action.

Do you see that Claude Code has finished running?

✔️ Yes, it finished

Awesome! Claude Code has created your status line script and updated your settings. Let's see it in action.

ⓧ Something went wrong

No worries. Here are some things to try:

  • Run /doctor inside Claude Code to check for issues.
  • If you see a statusLine error, open a new terminal window (not inside Claude Code) and open ~/.claude/settings.json in a text editor.

🍎 macOS

open ~/.claude/settings.json

🖼️ Windows

notepad %USERPROFILE%\.claude\settings.json
  • Make sure the statusLine entry has both a type and command field.
  • Save the file, type /exit to close Claude Code, then run claude to reopen it.
  • Need more help?

Still stuck?

Get help with your error or share your error with the NextWork community!

Verify the Status Line Appears

  • You should see the status line now in your terminal.
  • Do you see the status line?

✔️ I see the status line

Your status line is live!

You now have real-time session data right at your fingertips every time you use Claude Code.

ⓧ I don't see it

That's okay! Let's troubleshoot:

  • Close your current Claude Code session by typing /exit or pressing Ctrl+C twice.
  • Open a new Claude Code session by running claude in your terminal.
  • Look at the bottom of your terminal for the status line. You should see it immediately.

I'm still getting an error!

Run /doctor to check for issues. If you see a statusLine error:

  • Open ~/.claude/settings.json (How do I open the file?)
  • Make sure the statusLine entry has both a type and command field.
  • Save the file, type /exit to close Claude Code, then run claude to reopen it.

🙋‍♀️ Still stuck?

Get help with your error or share your error with the NextWork community!

Check Your Settings

Now let's look at the configuration file that powers your status line.

  • Open a new terminal window (not inside Claude Code) and open your settings file:

🍎 macOS/Linux

open ~/.claude/settings.json

🖼️ Windows

notepad %USERPROFILE%\.claude\settings.json
  • Look for the statusLine section. Can you see where your status line settings have been updated?

What am I looking at?

This is the JSON configuration file where Claude Code stores your preferences. The statusLine section you see here is what connects Claude Code to the script you just generated. It has four key fields:

  • env.CLAUDE_CODE_ENABLE_STATUSLINE turns the status line feature on.
  • statusLine.type tells Claude Code this is a script it needs to execute.
  • statusLine.command points to the actual file that produces your status line output.
  • The script path in command is the statusline.js file Claude just created for you.

Your status line is live. Next, you will customize it with a visual progress bar.

Customize Your Status Line

Your status line is live and showing real data. But right now it is plain text, which can be hard to scan at a glance.

In this step, you will prompt Claude Code to redesign it with colored background sections for each piece of info, a visual progress bar that fills up as your context grows, and a context token counter so you always know exactly where you stand.

In this step, get ready to:

  • Prompt Claude Code to customize your status line with colored sections and a progress bar.
  • Make it your own with a freestyle customization.

Customize With a Prompt

Right now your status line shows plain text. You will ask Claude Code to add colored background sections, a visual progress bar that fills up as your context usage grows, and a token counter that shows how many tokens you have used out of your total.

  • In your Claude Code session, paste the following prompt:
Customize my status line at ~/.claude/statusline.js to show: 1. A colored dot and the model name with context size (e.g. "Opus 4.6 (1M context)") 2. A money icon and the session cost 3. Context usage showing tokens used vs total 4. A 10-block progress bar for context usage using filled and empty block characters. Give each section a different background color so they are easy to tell apart. Keep reading JSON from stdin. Update ~/.claude/settings.json if needed.
  • Claude Code will ask you to confirm changes to your script.
  • You may see: Do you want to override statusline.js? Select Yes.
  • Claude Code rewrites your script with the new layout and colors.

What just changed?

Claude Code updated your script to include a progress bar, colored sections, and a token counter. It uses ANSI escape codes behind the scenes, which are special character sequences that tell your terminal to display text in color. You will learn more about these in the Secret Mission.

  • Type /exit to close Claude Code, then run claude to reopen it and see your progress bar in action.
  • Your status line should now show filled and empty blocks that update as your context usage changes.

Make It Yours

Now it is your turn.

  • Prompt Claude Code to change your status line however you like.

Not sure what to add?

Check out the Claude Code status line documentation for inspiration, or ask in the Community to see what others have built.

Here are some ideas to get you started:

  • Add an emoji or icon that represents you.
  • Change the colors to match your terminal theme.
  • Add the current date or time.
  • Show the number of files in your project.
  • Rearrange the sections in a different order.

There is no wrong answer here. Experiment, have fun, and make your status line feel like yours.

Your customized status line is ready. Next up, take on the Secret Mission to add color-coded context warnings that tell you exactly when to act.

Secret mission

Your status line shows context usage as a number, but how do you know when it is time to act? In this secret mission, you will add color-coded warnings that tell you exactly when to run /compact or /clear, and learn how context management connects to your rate limits.

In this secret mission, get ready to:

  • Understand how /usage tracks your rate limits across sessions.
  • Prompt Claude Code to add color-coded context warnings to your status line.
  • Review what Claude built and understand how ANSI escape codes work.

Add Color-Coded Context Warnings

Clean Up Your Resources

Clean Up Your Resources

Decide whether to keep your resources running, pause them to come back later, or delete them entirely. This project runs entirely locally, so there are no ongoing costs.

Resources you used:

  • ~/.claude/statusline.js (the Node.js script)
  • ~/.claude/settings.json (modified to add the statusLine field)

✔️ Keep everything running

No action needed. Choose this if you're still actively building or want to keep testing right away.

Your status line is passive. It runs locally when Claude Code is open and consumes no resources when Claude Code is closed.

✋ Pause - I'll come back to this later

Shut down running processes to free up memory, but keep all your files and data so you can pick up where you left off.

Your status line only activates inside a Claude Code session and stops automatically when you close it. No processes need to be stopped manually.

ⓧ Delete - I don't want to use this again

Remove all project resources so your terminal goes back to the default Claude Code experience.

🍎 macOS/Linux

  • Open a new terminal window and run:
open ~/.claude/settings.json
  • Find the "statusLine" section and delete the entire block, including the curly braces. Save the file.
  • Back in your terminal, delete the status line script:
rm ~/.claude/statusline.js

🖼️ Windows

  • Open a new terminal window and run:
notepad %USERPROFILE%\.claude\settings.json
  • Find the "statusLine" section and delete the entire block, including the curly braces. Save the file.
  • Back in your terminal, delete the status line script:
del %USERPROFILE%\.claude\statusline.js
  • Close Claude Code by typing /exit, then reopen it by running claude in your terminal. The status line at the bottom should be gone, confirming everything has been removed.

Nice Work

Nice Work

Nice work! You've just set up a live status line in Claude Code that shows your model, context usage, and session cost in real time.

You've learned how to:

  • 🛠️ Install and verify that Claude Code is working in your terminal.
  • ⚙️ Configure a Node.js-powered status line that reads live session data and displays it in your terminal footer.
  • 📊 Understand what model.display_name, context_window.used_percentage, and cost.total_cost_usd mean for your coding sessions.
  • 🧹 Monitor your context window percentage and know when to use /compact vs /clear.
  • 🎨 Customize the status line script to add a visual ASCII progress bar.
  • 💎 Add color-coded context warnings with ANSI escape codes and /compact vs /clear advice.

Ready to quiz yourself?

p.s. Does it say "Still tasks to complete!" at the bottom of the screen?

This means you still have screenshots left to upload, or questions left to answer!

  1. Press Ctrl+F (Windows) or Command+F (Mac) on your keyboard.
  2. Search for the text Return to later.
  3. Jump straight to your incomplete tasks!
  4. 🙋‍♀️ Still stuck? Ask the community!