Your first agent

Initialize a project

Nexus agents work on any Git repository. To get started, navigate to a project directory and initialize it:

cd ~/projects/my-app
nexus init --repo .

The nexus init command indexes your codebase and builds a dependency graph. For a medium-sized project (10k files), this takes approximately 30 seconds. You will see output like:

Indexing 847 files across 12 modules...
Dependency graph built in 1.7s
Created nexus.yaml - customize your agent configuration

Deploy your agent

With your project initialized, deploy an agent:

nexus deploy --name my-first-agent

This command starts an agent with default settings. The agent will load the Nexus-1 model, establish a memory layer, and begin listening for tasks. You should see:

Deploying agent "my-first-agent"...
  / Loading model: nexus-1 (default)
  / Connecting memory layer
  / Agent online

Assign a task

Now that your agent is running, give it a task. Start with something simple:

nexus ask "Find all TODO comments across the codebase and summarize them by category"

The agent will plan its approach, search the codebase, and produce a summary. You can monitor its progress with:

nexus status --agent my-first-agent

Review results

When the agent completes its task, it generates a plan or report. To view the results:

nexus logs --agent my-first-agent --tail 30

This shows the agent's reasoning trace and tool calls. You can see exactly how the agent arrived at its conclusions.

Understanding the agent lifecycle

When you deploy an agent, it progresses through a well-defined lifecycle. Understanding this lifecycle helps you debug issues and optimize performance.

Initialization: The agent loads the model into memory (Nexus-1 or your configured model), establishes the memory layer connection, and registers available tools from nexus.yaml. For first-time deployment, this takes 10-30 seconds depending on model size and network speed. Subsequent deployments are faster because model weights are cached (~2-4 seconds).

Idle: The agent is ready but has no active task. It maintains a heartbeat connection to the Nexus platform and listens for task assignments. Idle agents consume minimal resources (~200MB memory, negligible CPU). Agents auto-suspend after 30 minutes of inactivity on the free tier.

Planning: When you assign a task, the agent first plans its approach. It analyzes the codebase structure, identifies relevant files, and decomposes the task into sub-steps. You can see the plan before the agent executes it (if require_review: true in nexus.yaml). The plan includes: goal restatement (confirms the agent understood the task), approach summary (high-level strategy), step list (concrete actions with file paths), and estimated completion time.

Execution: The agent works through its plan step by step, using tools to read files, write code, run tests, and search documentation. Each step is logged with the tool call, its output, and the agent's reasoning. You can tail the logs in real-time with nexus logs --agent my-agent --follow.

Review (if enabled): When the agent completes a step that modifies code or requires human judgment, it pauses and presents the proposed changes for review. You can approve, request changes, or provide additional guidance. The agent incorporates feedback and continues.

Completion: The agent summarizes what it did, lists all files changed, and provides a rationale for key decisions. The summary is saved to the agent's memory for future reference.

Working with task templates

For repeated tasks, you can create task templates that pre-fill common patterns. Templates are stored in a .nexus/templates/ directory in your project root:

# .nexus/templates/add-endpoint.yaml
name: Add API endpoint
prompt: "Add a new {{method}} endpoint at {{path}} that {{description}}"
constraints:
  - "Follow existing error handling patterns in the module"
  - "Include OpenAPI documentation"
  - "Add unit tests for success and error cases"

Use the template with variable substitution:

nexus ask --template add-endpoint \
  method=POST path=/users description="creates a new user"

Debugging agents

When an agent produces unexpected results, use these debugging techniques. Inspect the reasoning trace: nexus logs --agent my-agent --format detailed shows every reasoning step the agent took. Look for steps where the agent made incorrect assumptions or missed context. Re-run with verbose mode: nexus ask "your task" --verbose streams the agent's thinking in real-time. Check tool call accuracy: The logs show each tool call with its input parameters and output. Look for cases where the agent called the wrong tool or provided incorrect parameters. Review memory context: nexus memory --agent my-agent --list shows what the agent remembers. Incorrect behavior is often caused by outdated or incorrect memories.

Working with agent logs

Agent logs are your primary tool for understanding what an agent did and why. Each log entry contains: a timestamp, the action type (reasoning_step, tool_call, tool_result, task_complete, error), the agent's internal reasoning (the chain-of-thought leading to this action), tool inputs and outputs (if applicable), and the agent's confidence in the action (0-100).

View logs in different formats:

# Compact format (default)
nexus logs --agent my-agent --tail 10

# Detailed format with reasoning traces
nexus logs --agent my-agent --format detailed --tail 5

# JSON for programmatic access
nexus logs --agent my-agent --format json --tail 100

# Real-time streaming
nexus logs --agent my-agent --follow

Compact format shows one line per action: [12:34:56] REASONING Step 4/12: Analyzing auth middleware (conf: 87). Detailed format expands each entry with the full chain-of-thought text and tool I/O. Use detailed format when debugging failures.

Handling agent failures

Agents fail sometimes. Here'''s how to handle common failures. Tool execution error: The agent tried to use a tool but it failed (e.g., compilation error, network timeout). Check the tool output in the logs. Common fixes: retry the task, check tool configuration in nexus.yaml, or verify external service availability. Context overflow: The agent ran out of context window space. The agent should handle this by checkpointing and continuing, but if it fails, break your task into smaller subtasks. Incorrect output: The agent completed the task but produced wrong results. Inspect the reasoning trace to find where the agent went wrong. Provide corrective feedback in a follow-up task: "The approach you used is incorrect because... Please fix it." The agent will incorporate this feedback into its plan.

Auto-retry pattern: For transient failures, you can configure automatic retries in nexus.yaml:

retry:
  max_attempts: 3
  backoff: exponential
  on_failure: restart_from_checkpoint

Multi-agent task examples

Once you are comfortable with single agents, try these multi-step workflows. Code review workflow: Deploy one agent for correctness checking, another for security review, and a third for style compliance. Each agent reviews the same PR from its perspective. Compare outputs to catch category-specific issues. Documentation generation: An agent analyzes your codebase and generates API documentation. A second agent reviews the documentation for accuracy and completeness. A third agent formats and publishes it. Migration workflow: One agent plans the migration steps, a second executes each step, and a third verifies the results. This separation of concerns reduces error rates.

Next steps

Congratulations! You have deployed and interacted with your first Nexus agent. Proceed to Step 3: Agent configuration to learn how to customize your agent's behavior.