Quickstart

This guide walks you through your first TatsuCode session. In 5 minutes, you'll understand the workflow and be ready for real projects.

Prerequisites

Before starting:

• TatsuCode is running
• You've configured an AI provider (see Installation)
• You have a project folder to work with

The Interface

TatsuCode uses a terminal-style chat interface:

• Top bar — Shows current directory, selected model, and token usage
• Chat area — Your conversation with the AI
• Input area — Type messages, run slash commands, paste images, or drag in files/folders

The Workflow

1. Type naturally to ask questions or give tasks
2. Use slash commands (type /) for configuration and actions
3. Use @filename to reference files quickly
4. Press ESC key to cancel any operation

Starting a Session

1. Open a Project

When TatsuCode starts, open your project:

/new C:\Projects\my-app

Or use /projects to select from recent projects.

2. Select a Model

Choose an AI model:

/models

Use arrow keys to navigate, Enter to select. Popular choices:

• Claude Opus 4.6 — Excellent for complex reasoning and coding
• GPT-5.3 Codex — Strong all-around coding model
• Gemini 3 Pro — Great for large-context analysis

3. Start Talking

Just type naturally:

> What does this project do?

TatsuCode analyzes your codebase and responds.

Basic Interactions

Asking Questions

> Explain the authentication flow
> Where is the database connection configured?
> What frameworks does this project use?

Making Changes

Request edits directly:

> Add input validation to the login form
> Fix the bug in handleSubmit
> Refactor this function to use async/await

TatsuCode shows a diff before applying changes.

Running Commands

> Run the tests
> Build the project
> Start the dev server

You'll be asked to approve commands before execution.

Quick Reference Syntax

@ File References

Type @ to quickly reference files:

> Explain @config.json
> What does @src/utils/auth.ts do?
> Compare @oldFile.js with @newFile.js

Files referenced with @ are automatically read into context.

Drag & Drop Attachments

You can also drag items directly into the input area:

• Single files
• Multiple files
• Entire folders
• Items from inside or outside the current project

If an item can't be fully read, TatsuCode still keeps a path reference so the AI can reason about where it lives.

Slash Commands

Type / to see all commands:

Press Tab to autocomplete commands.

AGENTS.md and Skills (Beginner Tip)

These are different tools:

• Use AGENTS.md for always-on project context and rules
• Use /skills for specialized workflows you load only when needed

/init analyzes your repository and creates or updates AGENTS.md with practical project guidance.

See:

• AGENTS.md
• Agent Skills
• Settings

Example Session

Here's a typical workflow:

/new ~/projects/my-api

> What does this Express API do? Give me a quick overview.

TatsuCode: I'll analyze the project structure...

[Reads package.json, src/index.ts, routes/]

This is a REST API for user management with:
- Authentication via JWT
- CRUD operations for users
- PostgreSQL database with Prisma ORM

Main endpoints:
- POST /auth/login - User login
- GET /users - List users (protected)
- POST /users - Create user
...

> I'm getting a "token expired" error. Find and fix the issue.

TatsuCode: I'll investigate the JWT handling...

[Reads src/middleware/auth.ts]

Found the issue on line 23. The token expiration check 
uses the wrong comparison operator.

[Shows diff]

- if (decoded.exp > Date.now())
+ if (decoded.exp * 1000 < Date.now())

Apply this fix?

> Yes, apply it. Then run the tests.

[Applies fix to src/middleware/auth.ts]

Running tests...

[Executes: npm test]

✓ 45 tests passed

Permissions

TatsuCode asks permission before:

• Writing files — Shows diff first
• Running commands — Shows command before execution
• Deleting files — Requires explicit approval

Quick Permission Keys

In permission dialogs, use number keys:

• 1 — Allow once
• 2 — Allow for this session
• 3 — Always allow
• 4 — Deny

Tips for Effective Use

Be Specific

Instead of:

> Fix the bug

Try:

> Fix the null pointer exception in UserService.getUser() 
  when the user ID doesn't exist in the database

Provide Context

> This is a Next.js 14 project using App Router. 
  Add a new API route at /api/products that returns 
  product data from the Prisma database.

Use Sessions

Name important sessions for easy recall:

/session-rename "Feature: Payment Integration"

Later, use /session to resume.

Monitor Usage

Keep an eye on token consumption:

/usage

If context gets full, use /compact to compress the conversation.

Undoing Changes

Made a mistake? TatsuCode tracks all file edits:

> Undo the last change to config.json
> Revert auth.ts to its original state
> Show me the edit history for this session

Common Issues

"API key not configured"

Run /connect (or /providers) and set up your AI access.

"Model not responding"

Try a different model with /models, or check your API key.

"Permission denied"

TatsuCode may need approval. Check the permission prompt and approve if appropriate.

Context getting full

Use /compact to compress the conversation, or /new to start fresh.

See Troubleshooting for more help.

Next Steps

• Providers — Set up OAuth, API keys, local models
• Commands — Full command reference
• AI Capabilities — What TatsuCode can do
• Tools Reference — All available tools