Skip to main content

​
Your First Enki Session

This guide walks you through launching Enki, understanding the initial setup, and creating your first task.
Make sure you’ve completed the Installation steps before proceeding.

​
Launch the TUI

Navigate to any project directory (Git repository or not) and run: 
enki
This opens Enki’s terminal user interface (TUI).

​
First Run: Project Initialization

On first run in a new directory, Enki automatically:
1

Creates the .enki directory

Initializes the project structure:
.enki/
├── db.sqlite          # Task and execution state
├── events/            # Signal files for IPC
└── logs/
    └── enki.log       # Session logs
2

Initializes the database

Creates SQLite tables for tasks, executions, merge requests, and worker state.
3

Starts the coordinator

Launches the orchestration engine that manages agent processes and the task DAG.
You’ll see a chat interface ready to accept your instructions.

​
Understanding the Interface

The TUI consists of:
  • Chat Area: Main interaction space where you describe work and see responses
  • Task Status: Visual indicators showing running, completed, and failed tasks
  • Streaming Output: Live updates from agents as they work

​
Create Your First Task

Enki uses a coordinator agent to break down your requests into executable tasks. Let’s try a simple example:

​
Example: Code Documentation

In the TUI chat, type: 
Add documentation comments to all public functions in src/main.rs
Press Enter to submit.

​
What Happens Next

1

Coordinator analyzes your request

The coordinator agent (running via Claude Code) analyzes your instruction and decides how to break it into tasks.
2

Tasks are created

The coordinator creates one or more tasks with dependencies. For this example, likely a single task:
  • “Document public functions in src/main.rs”
3

Workers are spawned

For each task, Enki:
  • Creates a copy-on-write clone of your project at .enki/copies/<task-id>/
  • Spawns an ACP agent in that isolated copy
  • The agent works independently without affecting your main files
4

Work is merged back

When a worker completes:
  • Changes are committed to a branch in the copy
  • The branch is fetched back to your main repository
  • Changes are merged through Enki’s merge queue
  • You see the updates in your working directory

​
Real Terminal Output

Here’s what you might see: 
[You]: Add documentation comments to all public functions in src/main.rs

[Coordinator]: I'll create a task to add documentation to your public functions.

✓ Task created: Document public functions in src/main.rs
⚙ Spawning worker (standard tier)...
⚙ Worker started in copy: .enki/copies/task-a1b2c3d4/

[Worker task-a1b2c3d4]: Reading src/main.rs...
[Worker task-a1b2c3d4]: Found 3 public functions to document
[Worker task-a1b2c3d4]: Adding doc comments...
[Worker task-a1b2c3d4]: ✓ Documentation complete

✓ Worker completed
⚙ Merging changes from branch task/a1b2c3d4...
✓ Merge successful

[Coordinator]: Documentation has been added to all public functions in src/main.rs.

​
Multi-Step Workflows

Enki excels at complex, multi-step work with dependencies. Try: 
Add a new CLI command 'enki doctor' that checks system requirements,
then write tests for it, and finally add documentation
The coordinator will:
  1. Create a dependency graph (DAG)
  2. Implement the command first
  3. After implementation completes, run tests and documentation in parallel
  4. Merge changes in order

​
Parallel Execution

Enki runs independent tasks in parallel based on tier limits:
  • Light tier: Up to 5 concurrent workers (simple tasks)
  • Standard tier: Up to 3 concurrent workers (typical coding tasks)
  • Heavy tier: 1 worker at a time (complex refactors)

​
Working in Git Repositories

If your project is a Git repository, Enki:
  • Creates a task/<id> branch for each task
  • Commits worker output to that branch
  • Merges through a queue to avoid conflicts
  • Preserves your Git history with structured commits
In non-Git directories, Enki uses Git internally for tracking changes but doesn’t create a permanent repository.

​
Common Commands in the TUI

While chatting with the coordinator, you can:
  • Create tasks: Describe work naturally
  • Check status: “What tasks are running?”
  • Pause work: “Pause the refactoring task”
  • Cancel tasks: “Cancel all pending documentation tasks”
  • Retry failures: “Retry the failed test task”
  • Stop everything: “Stop all workers”

​
Coordinator Agent Behavior

The coordinator agent works directly in your main project directory, not in isolated copies. When it edits code, changes appear immediately in your working directory without automatic commits.
Worker agents, on the other hand, work in isolated copies and their changes are merged through the queue.

​
Checking Logs

If something goes wrong, check the logs: 
# View the end of the most recent session
tail -n 200 ~/.enki/logs/enki.log

# Find errors and warnings
grep "ERROR\|WARN" ~/.enki/logs/enki.log

# Per-agent session logs (timestamped JSON-RPC traffic)
ls ~/.enki/logs/sessions/
Log files use this format: 
══════════════════ SESSION START ══════════════════
[timestamp] INFO Starting coordinator...
[timestamp] DEBUG Spawning worker for task-abc123

​
Tips for Success

  1. Be specific: The more detail you provide, the better the coordinator can plan
  2. Use natural language: Describe tasks as you would to a colleague
  3. Check status frequently: Use “show status” to see what’s running
  4. Let it work: Agents work in isolated copies, so your main code stays safe
  5. Review merges: Check merged changes before committing to your main branch

​
Next Steps

Core Concepts

Learn how Enki’s DAG orchestration works

Task Management

Master creating, managing, and monitoring tasks

Merge Queue

Understand how changes are merged back

Troubleshooting

Solutions for common issues

​
Example Workflows

Here are some real-world examples to try:

​
Refactoring

Refactor the database module to use async/await,
update all call sites, and ensure tests pass

​
Feature Addition

Add a new API endpoint for user preferences,
include validation and error handling,
write integration tests,
and add OpenAPI documentation

​
Bug Fix

Fix the memory leak in the connection pool,
add a test that reproduces the issue,
and document the fix in CHANGELOG.md
Each of these will result in multiple parallel tasks with automatic dependency resolution.

Build docs developers (and LLMs) love

Get started for freeTalk to us