Three Core Workflows

Master these three essential workflows to become productive with Sypha CLI immediately.

1. Feature Development Flow

The most common workflow: implementing new features with AI assistance, reviewing changes, and committing with proper tracking.

Step-by-Step Walkthrough

1. Start a new session with your goal

sypha "Help me add user authentication with JWT tokens"

Sypha will analyze your codebase, understand existing patterns, and start implementing the feature.

2. Enable Auto-Edit mode for faster iteration

Press Ctrl+Y to toggle Auto-Edit mode. This automatically approves file changes so you can move faster.

Auto-Edit Mode: ENABLED
All file operations will be auto-approved
Press Ctrl+Y again to disable

Auto-Edit mode is great for rapid prototyping, but disable it (Ctrl+Y) when you want to review each change carefully.

3. Review changes as they happen

Even with Auto-Edit enabled, you can review what Sypha is doing in real-time. Watch the file operations in the terminal.

4. Check the diff before committing

/diff --staged

This shows a visual diff with:

Green background for additions
Red background for deletions
Line numbers in the gutter
Expand/collapse with Ctrl+S for large diffs

5. Commit with Sypha branding

/commit "Add JWT authentication with refresh tokens"

This creates a commit with:

Your commit message
Automatic co-authoring attribution: Co-Authored-By: Sypha AI <noreply@sypha.ai>
Git integration tracking

6. Push to remote

/push

Or use standard git commands:

! git push origin feature/auth

Complete Example

# Start Sypha
$ sypha "Implement password reset functionality"

# Enable auto-edit for speed
[Press Ctrl+Y]

# Sypha implements the feature...
# Files modified:
#   - src/auth/passwordReset.ts (created)
#   - src/routes/auth.ts (modified)
#   - src/emails/templates/resetPassword.html (created)

# Review changes
$ /diff --staged

# Looks good! Commit it
$ /commit "Add password reset with email verification"

# Push to remote
$ /push

# Session auto-saved ✓

2. Bug Investigation Flow

Debugging complex issues by leveraging AI to analyze logs, stack traces, and code patterns.

Step-by-Step Walkthrough

1. Switch to Debug mode

/mode debug

Or use the keyboard shortcut: Shift+Tab and select "debug"

Debug mode optimizes Sypha's behavior for troubleshooting:

Focuses on error analysis
Suggests debugging strategies
Helps trace execution flow
Identifies root causes

2. Describe the problem

Provide as much context as possible:

> Users are reporting 500 errors when uploading files larger than 5MB.
> The error logs show "ECONNRESET" but I can't figure out why.
> Here's the stack trace: [paste stack trace]

You can also attach error logs:

@error-log.txt analyze this error and find the root cause

3. Let Sypha analyze the codebase

Sypha will:

Search for related code
Analyze error patterns
Check configuration files
Review recent changes
Identify potential causes

4. Test the hypothesis

Sypha might suggest adding logging or instrumentation:

// Sypha adds debug logging
console.log('[DEBUG] Upload file size:', file.size);
console.log('[DEBUG] Memory usage:', process.memoryUsage());

5. Implement the fix

Once the root cause is identified:

> The issue is the default body parser limit. Increase it to 50MB.

Sypha implements the fix:

// src/server.ts
app.use(express.json({ limit: '50mb' }));
app.use(express.urlencoded({ limit: '50mb', extended: true }));

6. Create checkpoint before testing

/checkpoint create "Before testing upload fix"

This creates a git-integrated snapshot you can restore if needed:

# If something goes wrong
/checkpoint restore <checkpoint-id>

7. Verify and commit

# Test the fix
! npm test

# If tests pass, commit
/commit "Fix: Increase body parser limit for file uploads

Resolves 500 errors for files >5MB by increasing express
body parser limit from 1MB (default) to 50MB."

/push

Complete Example

# Switch to debug mode
$ /mode debug

# Describe the issue
> Our API returns 401 errors randomly, even with valid tokens.
> It happens more frequently during high traffic.

# Sypha analyzes...
> [Sypha] Found potential race condition in token validation
> [Sypha] Checking auth middleware...

# Sypha identifies the issue
> The problem is concurrent token refresh operations
> creating race conditions in the cache layer.

# Implement fix
> Add distributed locking for token refresh operations

# Checkpoint before testing
$ /checkpoint create "Before auth race condition fix"

# Sypha implements the fix with Redis-based locking...

# Test it
$ ! npm run test:integration

# Commit the fix
$ /commit "Fix auth race condition with distributed locks"

$ /push

3. Session Resume Flow

Never lose context. Resume work across restarts, machines, or after switching between projects.

Step-by-Step Walkthrough

1. List your sessions

/session list

You'll see a list of all saved sessions:

📋 Saved Sessions (5 total):

1. ⭐ user-auth-implementation
   ID: a1b2c3d4
   Last active: 2 hours ago
   Messages: 28
   Provider: anthropic/claude-sonnet-4-5

2. api-performance-optimization
   ID: e5f6g7h8
   Last active: 5 hours ago
   Messages: 15
   Provider: openai/gpt-4

3. database-migration-planning
   ID: i9j0k1l2
   Last active: 1 day ago
   Messages: 42
   Provider: anthropic/claude-sonnet-4-5

2. Search for specific sessions

/session search "authentication"

This searches session content and returns matches:

Found 2 sessions matching "authentication":

1. user-auth-implementation (a1b2c3d4)
   "...implementing JWT authentication with refresh tokens..."

2. oauth-integration (m3n4o5p6)
   "...adding OAuth 2.0 authentication for Google and GitHub..."

3. Select and restore a session

/session select a1b2c3d4

Or resume the most recent session:

/session resume

Sypha restores:

Full conversation history with all context
AI understanding of what you were working on
File operations history
Current working directory
Selected provider and model
Mode (code/plan/debug/architect)

4. Continue where you left off

Just pick up the conversation:

> Now let's add password reset functionality

Sypha remembers everything from the previous session and continues seamlessly.

5. Rename sessions for better organization

/session rename a1b2c3d4 "JWT Auth + Password Reset"

6. Mark important sessions as favorites

/session favorite a1b2c3d4

Favorited sessions appear with a ⭐ and can be filtered:

/session list --favorites

Complete Example

# Working on Monday
$ sypha "Help me implement a recommendation engine"
# ... work for an hour ...
# Session auto-saved every 5 seconds

# Emergency meeting! Close terminal
$ exit

# Resume on Tuesday
$ sypha
$ /session list

# Find yesterday's session
$ /session search "recommendation"

# Restore it
$ /session select x7y8z9

# Continue work
> Let's add collaborative filtering
# Sypha knows exactly where you left off

# Rename for clarity
$ /session rename x7y8z9 "Recommendation Engine v1"

# Mark as important
$ /session favorite x7y8z9

Advanced Session Management

Auto-save behavior:

Saves every 5 seconds (configurable)
Includes full conversation context
Persists to ~/.sypha/sessions/
Works offline

Session metadata:

/session show

Displays:

Session ID and name
Created and last modified timestamps
Message count
Current provider and model
Working directory
Git branch (if in a repo)
Total tokens used
Estimated cost

Delete old sessions:

/session delete <session-id>

Export session for sharing:

/export session a1b2c3d4 --format json

Combining Workflows

These workflows are building blocks. Combine them for powerful development patterns:

Example: Feature Development → Bug Found → Session Resume

# Day 1: Start feature
$ sypha "Add export to PDF functionality"
[Ctrl+Y to enable auto-edit]
$ /commit "Add PDF export with custom templates"
$ /push

# Day 2: Bug report comes in
$ sypha
$ /mode debug
> Users can't export PDFs with images

# Fix the bug
$ /checkpoint create "Before PDF image fix"
# ... Sypha fixes it ...
$ /commit "Fix PDF image rendering for base64 data"

# Day 3: Resume PDF feature development
$ /session search "PDF"
$ /session select <pdf-session-id>
> Now add batch export for multiple documents

Example: Investigation → Planning → Implementation

# Investigate performance issue
$ /mode debug
> API responses are slow under load

# Switch to planning mode
$ /mode plan
> Design a caching strategy for the API

# Sypha creates architectural plan
# Review and approve

# Switch to code mode for implementation
$ /mode code
> Implement the Redis caching layer from the plan

[Ctrl+Y] # Enable auto-edit
# ... Sypha implements ...
$ /diff --staged
$ /commit "Add Redis caching layer for API endpoints"

Keyboard Shortcuts Reference

Master these shortcuts for faster workflows:

Shortcut	Action	When to Use
`Ctrl+Y`	Toggle Auto-Edit	Start of feature work
`Shift+Tab`	Quick mode switch	Switching between debug/plan/code
`Ctrl+D`	Show TODOs	Track implementation progress
`Ctrl+E`	Reasoning history	Understand AI's decision process
`Ctrl+X`	Cancel streaming	Stop long responses
`Ctrl+S`	Expand/collapse diff	Reviewing large diffs
`!`	Shell mode	Execute shell commands

✅ Use descriptive session names for easy searching ✅ Enable Auto-Edit for rapid prototyping, disable for careful review ✅ Create checkpoints before risky changes ✅ Review diffs before committing ✅ Use appropriate modes (debug for bugs, plan for architecture) ✅ Search sessions by keywords when resuming work

DON'T:

❌ Leave Auto-Edit enabled when working on critical code ❌ Skip diff review before pushing ❌ Delete sessions immediately - keep them for context ❌ Use generic session names like "session-1" ❌ Forget to commit before switching sessions

These three workflows cover 90% of daily development tasks. Explore CLI Samples for more specialized use cases.

💡

CLI Samples More examples and use cases

📚

CLI Reference Complete command documentation

🔗

Hooks Integration Automate with custom scripts

Core Flows

Three Core Workflows

1. Feature Development Flow

Step-by-Step Walkthrough

Complete Example

2. Bug Investigation Flow

Step-by-Step Walkthrough

Complete Example

3. Session Resume Flow

Step-by-Step Walkthrough

Complete Example

Advanced Session Management

Combining Workflows

Example: Feature Development → Bug Found → Session Resume

Example: Investigation → Planning → Implementation

Keyboard Shortcuts Reference

Best Practices

DO:

DON'T:

On this page