Basic Usage

This guide covers the fundamentals of working with Codive day-to-day.

Starting Codive

Interactive Mode

Start an interactive session in your project directory:

cd your-project
codive

You’ll see a welcome message and a prompt where you can type requests:

Welcome to Codive! I'm ready to help with your codebase.
Type your request or question below.

>

One-Shot Mode

For quick tasks, pass your request directly:

codive "add a Dockerfile for this project"

Codive will complete the task and exit.

With Specific Context

Focus Codive on specific files or directories:

codive --context src/auth "review the authentication logic"

Interacting with Codive

Natural Language Requests

Codive understands natural language. You don’t need special syntax:

> create a function to parse CSV files
> why is this test failing?
> refactor the database module to use connection pooling

Multi-Turn Conversations

Codive maintains context throughout your session:

> add a user registration endpoint

Done! Created POST /api/users endpoint.

> add email validation

Updated the endpoint with email validation using the validator crate.

> also add password strength requirements

Added password validation: minimum 8 characters, must include
uppercase, lowercase, and a number.

Referencing Files

You can reference files directly:

> look at src/main.rs and explain the startup sequence
> the bug is in lib/auth.rs around line 45

What Codive Can Do

Read Files

Codive can read any file in your project:

> show me the contents of Cargo.toml
> what's in the config directory?

Write Files

Codive can create and modify files:

> create a new module called analytics
> add error handling to the parse function

Run Commands

Codive can execute shell commands:

> run the tests
> build the project and show any errors
> check for outdated dependencies

Search Code

Codive can search through your codebase:

> find all usages of the deprecated API
> where is the database connection configured?

Session Management

Continuing Work

Codive remembers context within a session. You can build on previous work:

> create a user model
[Codive creates the model]

> now add a repository for it
[Codive creates UserRepository using the model]

> add validation
[Codive adds validation to the model]

Starting Fresh

To clear context and start fresh:

> /clear

Or start a new session:

codive --new-session

Output Format

Code Changes

When Codive makes changes, you’ll see a diff-style output:

Updating src/lib.rs:

 use std::collections::HashMap;

  fn process_data(input: &str) -> Result<Data, Error> {
     // TODO: implement
     let mut cache = HashMap::new();
     parse_and_cache(input, &mut cache)?;
     Ok(Data::from_cache(cache))
  }

Explanations

When you ask for explanations, Codive provides structured responses:

> explain the error handling pattern here

This codebase uses the `thiserror` crate for custom errors.

The pattern works like this:
1. Each module defines its own error enum
2. Errors implement `std::error::Error` via the derive macro
3. The `?` operator propagates errors up the call stack

Example from src/api/error.rs:
[code snippet with annotations]

Keyboard Shortcuts

Shortcut	Action
`Ctrl+C`	Cancel current operation
`Ctrl+D`	Exit Codive
`Ctrl+L`	Clear screen
`Up/Down`	Navigate history
`Tab`	Autocomplete file paths

Tips for Effective Use

Be Specific

Instead of:

> fix the bug

Try:

> fix the null pointer exception in UserService.getById()
when querying a non-existent user ID

Provide Context

Instead of:

> add tests

Try:

> add unit tests for the email validation function,
covering valid emails, invalid formats, and edge cases

Iterate

Start broad, then refine:

> create a caching layer

[review output]

> make it use Redis instead of in-memory

[review output]

> add a TTL of 5 minutes for user data

Next Steps

Learn about configuration options
Explore available commands
Extend Codive with custom tools