# How Cody Works

Cody operates in four modes that shape how it approaches your request. The mode switches automatically. You just describe what you need.

| Mode  | Purpose                                                     | Activates when                                              |
| ----- | ----------------------------------------------------------- | ----------------------------------------------------------- |
| Chat  | Explore, research, answer questions, run existing workflows | Every conversation starts here                              |
| Plan  | Structure complex tasks before building                     | Multiple integrations, APIs, or scheduled data are involved |
| Build | Create workflows, apps, and automations                     | You ask Cody to create or significantly change something    |
| Debug | Fix broken workflows                                        | You report an error or something stops working              |

### Chat Mode

Chat is the starting point for every conversation. Cody stays here until you ask it to build something concrete.

Think of Chat as the research and discovery phase. Cody gathers context, answers questions, and validates integrations before committing to building.

### What Cody does in Chat

* Answers questions about the platform, integrations, and what is possible
* Researches topics using web search, documentation, and page scraping
* Runs your existing workflows when you point to them
* Tests integrations and APIs to validate they work before building
* Browses websites and extracts data on demand
* Searches your past conversations to recall previous work
* Collects credentials securely (never in plain chat text)

### What Cody will not do in Chat

* Edit or deploy code (that is Build mode)
* Fix bugs in existing services (that is Debug mode)
* Start building before understanding what you actually need

Before leaving Chat mode, Cody confirms requirements, checks relevant docs, tests integrations, collects credentials securely, and gets your agreement on what will be built.

### Plan Mode

Complex builds only.

When a request is complex enough to need structure, Cody creates a plan before writing code. This happens automatically.

#### When planning kicks in

* The build involves more than one integration (for example, Slack plus Google Sheets)
* Multiple external APIs need to be coordinated
* The workflow runs on a schedule or responds to triggers
* Both a frontend app and a backend service are needed

#### What the plan includes

A visual plan appears in the canvas panel covering:

* What will be built and how components connect
* Which integrations are involved and what access is needed
* How data flows from input to output
* Cost estimates where applicable
* What Cody needs from you (credentials, preferences, access)

Cody describes the outcome, not low-level implementation details. You approve the plan, then Cody handles the build.

Simple requests (single integration, straightforward logic) can skip planning and move directly to Build mode.

### Build Mode

Creating and deploying.

This is where things get made. Cody writes code, creates services, builds apps, deploys them, and runs automated tests in the background while staying engaged in conversation.

#### What gets built

| Request type                                 | What gets built                                                           |
| -------------------------------------------- | ------------------------------------------------------------------------- |
| Dashboard, landing page, or interactive tool | Web app (Next.js, TypeScript, Tailwind CSS) deployed to `*.codewords.run` |
| Automation, data pipeline, or scheduled task | Python backend service deployed to CodeWords                              |
| Interactive app with processing power        | Both frontend and backend service                                         |

#### Build pipeline stages

1. Research: finds relevant templates, integration patterns, and API docs
2. Build: writes the code (typically 5-17 minutes)
3. Deploy: makes it live
4. QA: runs automated tests
5. Deliver: presents the working result with a live demo

#### What you experience during build

While build runs in the background, Cody stays in conversation:

* It may ask you to connect an integration (OAuth popup appears in chat)
* It collects credentials through secure input (never plain text)
* It may ask configuration questions that shape the result, for example:
  * Which Slack channel should this post to?
  * What timezone are you in?
  * Do you want a custom domain like `my-dashboard.codewords.run`?

These questions are optional. If you step away, Cody uses sensible defaults and continues.

#### When build finishes

* For web apps: a live preview appears in canvas, then Cody asks for approval before production deployment.
* For backend workflows: Cody runs a realistic test once, then shares the URL you can trigger anytime.

If tests detect a problem, Cody investigates and fixes it when possible, or explains the exact input needed from you.

### Version control

Every build creates a version. Cody can roll back to previous versions if needed.

### Debug Mode

Fixing what is broken.

When something fails, Cody shifts to a surgical debugging approach. Instead of rerunning everything, it isolates the failing component and fixes that piece first.

#### How debugging works

1. Read: check logs, requests, and error details
2. Isolate: reproduce only the failing component
3. Understand: explain root cause in plain language
4. Fix: make the smallest necessary change
5. Test: verify the fix and run end-to-end validation
6. Regression test: confirm other behavior is still correct

#### Why isolation matters

If a workflow has five steps and step four fails, Cody tests step four first. This is faster, cheaper, and easier to diagnose than rerunning all five steps repeatedly.

#### Batch failure handling

When processing many items and some fail (for example, 100 items with 5 failures), Cody:

* Isolates one failing item
* Reproduces and fixes the issue
* Verifies on 2-3 more failing items
* Re-runs the full batch only after confidence is high

#### When Debug mode ends

* Issue fixed and confirmed: returns to Chat
* Issue requires redesign: transitions to Build
* Still blocked after repeated attempts: pauses, explains, and asks how you want to proceed

### How Modes Flow Together

#### Complex project

**Chat** -> **Plan** -> **Build** -> **Debug (if needed)** -> **Chat**

You describe the goal. Cody researches, asks clarifying questions, presents a plan for approval, builds and deploys, fixes issues if needed, and then suggests next steps.

#### Simple request

**Chat** -> **Build** -> **Chat**

If the request scope is clear and straightforward, Cody skips planning and builds directly.

#### Bug report

**Chat** -> **Debug** -> **Chat**

You report a failure, Cody investigates and fixes it, then confirms results.

### What Triggers Each Mode

| What you are doing                                                  | Mode  |
| ------------------------------------------------------------------- | ----- |
| Exploring ideas, asking what is possible, asking for cost estimates | Chat  |
| Running existing workflows, checking results, managing schedules    | Chat  |
| Asking Cody to research a topic or scrape a page                    | Chat  |
| Requesting work with multiple integrations or scheduled data        | Plan  |
| Asking Cody to create a workflow, app, or automation                | Build |
| Requesting major changes or new features in an existing service     | Build |
| Reporting an error or saying something is not working               | Debug |

### Good to Know

* You do not manually choose modes. Cody infers mode from your intent.
* Asking questions during build does not cancel build progress.
* Complex requests get a plan first and wait for your approval before build starts.
* Cody stays responsive during long builds and asks only essential configuration questions.
* Credentials are handled through secure input flows, not plain chat text.
* Debug mode is targeted and efficient, not brute-force rerun.
* Every change is versioned, and rollback is available when needed.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.codewords.ai/core-concepts/how-cody-works.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.