Hello from the Bob team

This is the first post on the Bob blog. It is written by the team building Bob, for the developers using it. We will use it to explain engineering decisions, share what we have learned shipping an AI development partner inside real codebases, and occasionally argue for a position. It is not documentation and it is not marketing — if you want either, we will link you to the right place.

For our first post, rather than walk through everything Bob does, we want to do three things:

Look at a few of Bob's core capabilities.
Share a set of practical tips for setting up a repository so Bob does its best work.
Explain how we approach security in a tool that has this kind of access to your code.

1. What developers actually spend their time on

A modern AI assistant can write a function from a description. That has been true for a while, and it is no longer the interesting question. The interesting question is what happens when the work is not "produce new code" but "modify a system that already exists" — finding the right place to make a change, understanding the conventions a team has settled on, keeping behavior consistent across files that have been growing for years. This is most of what professional software development looks like. Bob is built for this kind of work, and the design choices we describe in the rest of this post follow from that focus.

1.1. Modes: telling Bob what kind of work you are doing

Bob is not a single "do something useful" interaction. The mode you start a session in tells Bob what kind of work you are about to do, which tools it can reach for, and how proactive it should be.

Ask — read-only. Perfect for the “exploration phase”. Bob explains architecture and logic without making changes. Use this when diving into a legacy system or performing a sanity check on a piece of logic you didn't write.
Plan — Bob produces a plan for a change you are about to make: files to touch, edge cases to consider, suggested order of work. The output is a plan, not code.
Code — for actually making changes. Bob reads, writes, and tests within your project, following the conventions and rules you have set.
Advanced — extends Code mode through the Model Context Protocol (MCP), giving Bob access to your organization's specific tools and services: internal APIs, databases, proprietary tooling.
Orchestrator — for multi-step work that crosses modes. Bob switches between modes itself based on what the current step calls for, and is the right choice for larger pieces of work that mix exploration, planning, and execution.

Picking the right mode at the start of a session is one of the cheapest levers available for getting better output. A good habit, particularly on a codebase you do not know well or for a change with any real surface area, is to start in Ask or Plan and only switch to Code once you have a clear picture of the work. Going straight to Code feels faster in the moment, but that is where assumptions tend to slip through as actual changes and start accumulating as technical debt.

1.2. Bob tips: complexity metrics, in real time

We’ve all been there: you’re deep in the "zone," nesting one last conditional to handle an edge case, and suddenly a single function has grown into a thirty-line maze. In a typical workflow, that maze doesn't get untangled until a teammate points it out in a pull request hours later. Bob Tips changes the narrative by offering a refactoring proposal while the logic is still warm in your mind. As you type, continuous static analysis quietly monitors your open files. When a function crosses the line into high cyclomatic complexity or becomes difficult to maintain, Bob immediately flags it with a purple underline. A traditional linter just tells you that you've done something wrong; Bob Tips provides the way out. The focus of the tool is entirely on delivering actionable refactoring proposals:

Contextual Intelligence: Hovering over the purple underline doesn't just display a warning—it offers a specific, AI-generated strategy to untangle the logic right then and there. Seamless Execution: Clicking Fix with Bob instantly opens a dedicated chat. The AI already holds the function's context and is ready to execute the cleanup alongside you.

The metrics running in the background are just the plumbing. The valuable part is that a long-standing code-quality signal now drives an AI suggestion at the moment the developer is in the file, rather than surfacing in a code review three days later.

1.3. Review mode: code review, with the system reading along

Code review has done as much for software quality as any practice in the last two decades, and it is also where teams lose momentum. Bob does not replace human review. It does the parts that are mechanical, they can focus on high-level architecture and intent rather than hunting for "low-hanging" bugs.

Reviews run from the Review Panel in the sidebar or via /review in chat. There are two modes:

Branch comparison. This mode handles the "classic" diff. Use /review to audit uncommitted work against your current head, or /review <branch> to target a specific remote. It’s a pre-emptive strike against the "nitpicks" that usually clutter review threads.
Issue coverage. /review <issue-url> --issue-coverage validates that your local changes actually address what a GitHub issue asks for. This is the mode developers tell us they did not realize they wanted until they tried it. Findings appear in a dedicated panel, so you can review and decide to fix them with Bob. It’s a sanity check that confirms you didn't just write good code, but the right code.

1.4. Literate coding: intent, written next to the code

When you’re deep in a complex feature, referencing multiple files in a chat window is a chore. You find yourself typing "Look at the interface in types.ts and the service in api.ts, then update the logic here..." Bob flips this dynamic. By moving the interaction directly into the source file through Literate Coding, the editor itself becomes the interface. This isn't just about avoiding a side-panel; it’s about providing the AI with a sophisticated, multi-file map of your intent.

Express Intent Naturally: Toggle the mode with Cmd+M and write your logic in plain language or pseudocode. Your instructions appear in the editor in blue, living exactly where the implementation belongs.
Beyond the Single Line: While traditional chat often loses the "thread" of a complex project, Bob’s literate coding is evolving to bridge the gap between files. Developers can now provide context across multiple modules, ensuring that a change in a data model is reflected accurately in the associated controller.
Immediate Verification: Press Cmd+Enter and Bob generates the implementation in-place. Because the result is shown as an inline diff, you can audit the logic against the surrounding code before committing to the change.

The benefit is straightforward: the prompt lives where the code lives, with the surrounding file already serving as context. Current scope is single-file; multi-file support is on the roadmap.

1.5. Bob in the terminal

Bob Shell brings Bob's capabilities to the command line, and there are two ways of using it that we find particularly worthwhile.

The Terminal as a Workspace: Working with an AI development assistant inside the shell has emerged as a popular form factor in its own right — it pairs naturally with how many developers already drive Git, builds, and tests, and has become part of the daily workflow for a lot of teams. It’s the most reliable way to bring AI to remote servers or environments where a native IDE integration isn't available: Anywhere you have a terminal, you can have Bob.
From Deterministic to Adaptive Automation: Bob Shell shines in non-interactive sessions like scheduled jobs, and deployment scripts in CI/CD pipelines. Anywhere a script today shells out to a deterministic tool, it can shell out to Bob with full context of the surrounding repository — and the automation that comes out the other side is more adaptive than a fixed pipeline.

We will publish a follow-up post on what we have learned running Bob non-interactively in CI: the patterns that work well in practice, including PR summaries, risk flagging, and integration into existing automation.

2. Make your repository Bob-ready

The repositories where Bob produces its best work share a few traits in common. None of them are AI-specific — they are the same things that make a repository pleasant to work in for any developer — but each of them gives Bob more to work with.

Fast, reliable tests. If npm test (or your equivalent) takes five minutes or flakes intermittently, the iteration loop slows to a crawl and the feedback signal degrades. Tests under a minute are a multiplier for any developer; for an AI assistant working in tight cycles, they are essential.

Documented build and test commands. A Makefile, a top-level scripts section in package.json, or a README block — somewhere Bob can find "how do I run this." Without it, Bob has to infer, and inference is where mistakes enter.

Executable style. Linters and formatters that run on save or in CI. Bob picks up your conventions from these. Explicit, machine-checkable rules outperform implicit conventions every time.

An agents.md at the repository root. Project structure, key files, coding standards, do's and don'ts. This is the single highest-leverage file you can add for AI assistance. The right way to think about it is as a CONTRIBUTING.md written for an LLM rather than for a new hire.

Architecture documentation in markdown, alongside the code. Even short documents help. A docs/architecture.md that describes modules and their boundaries lets Bob answer "where does this go?" without re-deriving design from imports.

A few things we have learned along the way:

Large rules files reduce signal. Past a couple of hundred lines, model performance degrades. Split rules by area — agents.md at the repository root, scoped readme.md per package — rather than concentrating everything in one file.
Compound your engineering. When you finish a task, ask Bob to distill the relevant learnings back into the rules file or into a skill. The repository becomes a more productive environment as you use it.
Iterate, do not one-shot. A multi-turn conversation that lands the right change consistently outperforms a single long prompt that lands eighty percent of it.

3. Security and control

Bob has several layers of protection that work together rather than any single guardrail doing all the work. The short version, suitable for a first post:

Manually approve every action, or auto-approve by tool class (read-only versus write) once you trust the workflow.
.bobignore keeps Bob out of files it should not read — credentials, generated artifacts, anything sensitive.
Custom rules enforce coding standards on Bob the same way they enforce them on developers.
Automatic checkpoints make recovery from an undesired change a one-click action.
Your prompts are not used as training data!

Auto-approval, in particular, is worth being deliberate about. It is one of the main controls you have over how much Bob can do between checkpoints with you, and broadening it is a productivity gain that also asks a little more of you in deciding what falls inside that envelope and what does not. A sensible default for most developers is to auto-approve read-only tools, leave write actions on manual approval for at least the first few weeks, and be especially considered with anything that runs shell commands or reaches systems beyond your local working tree. The other controls in the list — .bobignore, custom rules, checkpoints — are designed to compose with auto-approval rather than substitute for it.

4. Get started

Install IBM Bob from our website, or install Bob Shell via your terminal of choice.
Review our best practices guide and consult our security guidelines.
Start with a real task — You learn best when Bob is helping with real problems.

Links