How to Use OpenCode CLI Todos Feature Effectively with Sidebar Progress Tracking

Mar 30, 2026

I was refactoring a large codebase with OpenCode CLI. Halfway through, I realized I had no idea what was done and what remained. Was the AI still working? Did it forget something? I couldn’t tell.

Then I found the todos feature. And the sidebar. Together, they changed how I work.

Complex coding tasks have many steps:

Analyze the codebase
Identify files to modify
Write the implementation
Add tests
Update documentation

When OpenCode works on these tasks, I used to stare at the terminal. Waiting. Hoping it remembered everything.

Sometimes it forgot steps. Sometimes I interrupted it unnecessarily. I had no visibility into progress.

Reddit user “franz_see” described it perfectly: “Todos - one of the more useful features of OpenCode imho. Partner that with the sidebar, and you’d have yourself like a pseudo-progress bar because you can see how many todos has it accomplished vs how many are still left.”

That was exactly what I needed.

OpenCode has a built-in tool called TodoWrite. When the AI works on multi-step tasks, it creates todo items.

Here’s what that looks like:

┌─────────────────────────────────────────┐
│ TODOS                                    │
├─────────────────────────────────────────┤
│ [✓] Analyze authentication flow         │
│ [✓] Find all password validation code   │
│ [→] Implement new validation rules       │
│ [ ] Update existing tests                │
│ [ ] Add new test cases                  │
│ [ ] Update API documentation             │
└─────────────────────────────────────────┘

The checkmarks show completed items. The arrow shows what’s in progress. Empty boxes show what remains.

This is visibility. This is control.

The sidebar is off by default. Here’s how to show it:

┌─────────────────────────────────────────┐
│                                         │
│   Press: Ctrl + X, then B               │
│                                         │
│   Or use Command Palette: Ctrl + P      │
│   Then search: "Toggle Sidebar"          │
│                                         │
└─────────────────────────────────────────┘

The sidebar appears on the right side of your terminal. It shows:

Current todos
Progress percentage
Session information

Reddit user “franz_see” also mentioned: “Second, if you want to maximize OpenCode, ctrl+p. There’s a lot of good stuff there.”

The command palette (Ctrl+P) is worth exploring. It reveals all available commands, including sidebar controls.

Why Todos Matter

1. Visibility

I can see what the AI is doing. No more guessing.

Before:  [????????????????] Is it working?
After:   [✓✓✓→□□□□□□] 3 of 8 complete

2. Accountability

The AI commits to specific tasks. I can verify it follows through.

If I see:

[✓] Add OAuth support
[ ] Fix existing auth tests

And the session ends without fixing tests, I know to ask about it.

3. Planning

Todos force the AI to plan before executing. This produces better results.

I often see OpenCode pause at the start of a complex task. It creates a todo list first. Then works through each item.

The Workflow: Step by Step

Here’s my typical session:

Step 1: Describe a Complex Task

"I need to add rate limiting to the API endpoints.
The limits should be configurable per endpoint,
and we need logging for rate limit hits."

Step 2: Watch the Todo List Form

OpenCode creates todos automatically:

┌─────────────────────────────────────────┐
│ TODOS                                    │
├─────────────────────────────────────────┤
│ [ ] Analyze existing API structure       │
│ [ ] Identify endpoints needing limits    │
│ [ ] Design rate limit configuration      │
│ [ ] Implement rate limiting middleware   │
│ [ ] Add per-endpoint configuration       │
│ [ ] Implement logging                    │
│ [ ] Add tests                            │
│ [ ] Update documentation                 │
└─────────────────────────────────────────┘

┌─────────────────────────────────────────┐
│ TODOS (4/8 complete)                     │
├─────────────────────────────────────────┤
│ [✓] Analyze existing API structure       │
│ [✓] Identify endpoints needing limits   │
│ [✓] Design rate limit configuration     │
│ [✓] Implement rate limiting middleware  │
│ [→] Add per-endpoint configuration      │
│ [ ] Implement logging                   │
│ [ ] Add tests                           │
│ [ ] Update documentation                │
└─────────────────────────────────────────┘

Step 4: Intervene When Needed

If I see it missing something important, I interrupt:

"Before you finish, also add a /status endpoint
that shows current rate limit usage."

OpenCode adds to the todo list:

[✓] ... (previous items)
[ ] Add /status endpoint
[ ] ... (remaining items)

I used to ignore the sidebar. I thought it was just decoration.

It’s not. It’s a progress dashboard.

Enable it at the start of every session. Keep it visible. Check it when the AI pauses.

Common Mistake: Todos Disabled for Subagents

Subagents are specialized AI workers that handle specific tasks. By default, they might not create todos.

To ensure todos work for subagents, check your configuration:

{
  "subagents": {
    "enableTodos": true,
    "showProgress": true
  }
}

This ensures every subagent reports progress the same way.

Configuration Options

Here’s a complete configuration for maximizing todo visibility:

{
  "todos": {
    "enabled": true,
    "showInSidebar": true,
    "autoCreate": true,
    "requireCompletion": false
  },
  "sidebar": {
    "defaultVisible": true,
    "position": "right",
    "width": 40
  },
  "subagents": {
    "enableTodos": true,
    "inheritSettings": true
  }
}

Key options explained:

Setting	Purpose
`todos.enabled`	Turn on todo tracking
`todos.showInSidebar`	Display todos in sidebar
`todos.autoCreate`	AI creates todos for complex tasks
`sidebar.defaultVisible`	Show sidebar on startup

When Todos Are Most Useful

Not every task needs todos. They shine with:

Complex Multi-step Tasks

"Refactor the authentication module to support
OAuth2, SAML, and custom providers."

This creates a structured plan.

Code Reviews

"Review the codebase for security issues."

Todos track each finding.

Large Refactors

"Convert all JavaScript files to TypeScript."

Todos show which files are done.

Simple tasks don’t need todos:

"What does the 'async' keyword do in JavaScript?"

No todos necessary. Just a quick answer.

Summary: The Visibility Formula

┌─────────────────────────────────────────┐
│                                         │
│   TodoWrite Tool   +   Sidebar (Ctrl+X B)│
│          ↓                    ↓         │
│    Structured Tasks    Visual Progress  │
│                    ↓                    │
│              Full Visibility             │
│                                         │
└─────────────────────────────────────────┘

The TodoWrite tool creates structure. The sidebar displays progress. Together, they give you control.

My Workflow Now

Start OpenCode session
Press Ctrl+X, then B to show sidebar
Describe complex task
Watch todo list appear
Monitor progress in real-time
Intervene if something is missed
Verify all items completed

I no longer wonder if the AI is working. I can see it. I can verify it. I can guide it.

Final Words + More Resources

My intention with this article was to help others share my knowledge and experience. If you want to contact me, you can contact by email: Email me

Here are also the most important links from this article along with some further resources that will help you in this scope:

Oh, and if you found these resources useful, don’t forget to support me by starring the repo on GitHub!