Features

Cosine CLI is more than a chat interface — it’s a full development environment with checkpointing, background tasks, session history, and multi-project support. This page covers the major features and how to use them.

Checkpointing

At the end of each agent turn, Cosine CLI automatically creates a checkpoint — a lightweight git commit that captures exactly the files the agent edited. This gives you a full undo history for every change the agent makes.

How it works

1. As the agent edits files, each change is recorded internally.
2. When the agent finishes its turn, a commit is created containing only those edits.
3. The commit message is AI-generated from the conversation context, falling back to cos: checkpoint #N — M files.
4. A checkpoint marker appears in the timeline:

──── checkpoint · 3 files ────

Each commit includes a Co-Authored-By: Cosine CLI (<model>) <agent@cosine.sh> trailer so checkpoint commits are easy to identify in your git log.

Reverting and reapplying

Checkpoints can be reverted to restore files to their state before the agent’s changes, and reapplied later if needed. The patch files are stored alongside the session data for recovery.

Disabling checkpoints

If you don’t want the agent to create checkpoint commits, you can disable it per session:

cos start --checkpointing=false

Or globally in your config file:

[config]
checkpointing = false

---

Session History

Every conversation is automatically saved so you can pick up where you left off. Sessions store the full conversation context, model, mode, and system prompt.

Resuming a session

1. Open the commands menu with / or Ctrl+P
2. Select Resume session
3. Browse previous sessions — each shows its title, date, and working directory
4. Use the filter input to search by name
5. Toggle “Only show sessions for this directory” to narrow results to the current project

After resuming, you’ll see a confirmation: “Loaded session from <date> into context” and the conversation picks up with the full history restored.

Tip

Sessions are stored under ~/.cosine/sessions/ organized by date. You can resume a session from any directory, not just the one it was originally started in.

---

Background Tasks

Background tasks let you spin off work to a separate agent while you continue working in your main session. Each task runs on its own git branch in a worktree.

Launching a task

1. Open the commands menu with / or Ctrl+P and select Task → Start a background task
2. Or press n in the Agents panel (Ctrl+3 / Alt+3)

Task configuration

When launching a task you can configure:

Field	Description
Task prompt	Describe what the agent should do
Base branch	Branch to start from (defaults to main)
Branch name	Auto-generated or custom branch name
Execution target	Local worktree or Remote

Background tasks appear in the Agents panel where you can monitor progress, view diffs, or kill them.

---

Side Panel

The side panel provides quick access to session info, terminals, agents, and changes. Toggle it with Ctrl+/ and switch focus with Ctrl+`.

Overview (Ctrl+1 / Alt+1)

Displays session metadata at a glance:

• Model and context window size
• Mode, prompt, and version
• Changes — file count with additions/deletions
• Tool usage — a visual sparkline showing token usage over time, color-coded by type (yellow = Read, purple = Edit, blue = Web, red = Exec)
• Todo list — current progress with pending/in-progress/completed counts
• Terminals — active terminal sessions with status indicators
• Tools — list of all available tools

Terminals (Ctrl+2 / Alt+2)

Manage interactive terminal sessions:

Key	Action
n	Open a new shell session
Enter	View the selected terminal (full interactive PTY)
x	Kill the selected terminal
Ctrl+Esc	Return from a terminal to the list

Agents (Ctrl+3 / Alt+3)

Monitor all running agents — your primary session, background tasks, and subagents:

Key	Action
n	Start a new background task
Enter	View the selected agent
a	Open agent actions (diff, apply, kill)
x	Kill the selected agent

Subagents spawned by the primary agent appear indented under their parent.

Changes (Ctrl+4 / Alt+4)

Shows a syntax-highlighted git diff of all files the agent has modified in the current session.

---

Timeline

The timeline is the main conversation view. It renders user messages, assistant responses, tool calls, reasoning blocks, plans, todo lists, checkpoint markers, and more.

Navigating messages

Key	Action
Shift+↑ / Shift+↓	Enter message selection, jump between user messages
↑ / ↓	Move between items within a selected response
Space	Expand or collapse all blocks for the selected message
y	Copy the selected assistant output to clipboard
Ctrl+O	Toggle expand/collapse of a selected execution block
PgUp / PgDn	Page up / down
Home / End	Jump to top / bottom

Visual indicators

• User messages have a gray background with a colored left border matching the current mode
• Tool calls are grouped into collapsible execution blocks with a ⏺ Tools header
• Reasoning blocks are expandable and show token count + duration
• Checkpoint markers appear as horizontal separators between turns

---

Linked Projects

Link additional project directories to give the agent access to multiple codebases in a single session.

Adding a linked project

1. Open the commands menu with / or Ctrl+P
2. Select Link Project
3. Enter the path to the project directory
4. Choose the scope:
   • Session — access lasts until you exit
   • Permanent — saved and restored in future sessions

Once linked, the agent can read and search files across all linked projects. Tools like grep and filename_search accept a directory parameter to target a specific linked project.

---

Memory

Cosine CLI maintains project knowledge through two mechanisms:

AGENTS.md

An AGENTS.md file in your repository root serves as persistent context that the agent reads at the start of every session. Use it to document:

• Project architecture and conventions
• Build and test commands
• Team preferences and coding standards
• Non-obvious setup steps

Initialize one with:

cos init

Session memories

During a conversation, the agent can save reusable facts using the save_memory tool — things like build fixes, project conventions, or user preferences. These are stored in .cosine/agents.md and automatically loaded in future sessions.

---

Modes

Cosine CLI has four operating modes that control how the agent behaves. Cycle between them with Shift+Tab:

Mode	Label	Description
Manual	Normal	Default — asks for confirmation before mutating tools
Auto	Auto	Runs tool calls without asking for approval
Plan	Plan	Agent creates a plan before executing — no direct edits
Swarm	Swarm	Enables subagent orchestration for parallel work

For a detailed breakdown of each mode, see Modes.

---

Skills

Skills are reusable packages that extend the agent with specialized knowledge, templates, and scripts. They can be installed from git repos, local paths, or npm packages.

Quick reference:

# Install a skill
cos skills add https://github.com/example/my-skill

# List installed skills
cos skills list

In the TUI, browse skills from the commands menu (/ → Skills) or reference a skill inline with $skill-name.

For full documentation, see Skills.

---

MCP (Model Context Protocol)

MCP connects external tools and APIs to Cosine CLI using an open standard. Configure servers in ~/.cosine/mcp.json to give the agent access to databases, file systems, APIs, and more.

For setup and examples, see MCP Configuration.

---

Next Steps

• Navigating the CLI — Keyboard shortcuts and TUI layout
• Configuration — All config options and flags
• Modes — Detailed mode behavior
• Skills — Installing and creating skills
• MCP Configuration — Connecting external tools