Pixel Assistant

An autonomous terminal assistant that spawns its own agents — and writes its own skills

← AI Lab

Try It

Step through a real ReAct agent run — auto-routing, tool calls, and a SPAWN sub-agent. Scripted client-side, so it never calls a live model.

Press “Step” to start the agent…
0/9

The actual code behind the loop:

src/skills/agent.py
def run(self, task: str, max_turns=None) -> AgentResult:
    self.messages.append({"role": "user", "content": task})

    for turn in range(max_turns or self.MAX_TURNS):
        if time.time() - self.start_time > Agent.MAX_EXECUTION_TIME:
            return self._timeout()           # hard wall-clock guard

        result = self.llm_fn(self.messages)  # provider-agnostic call

        # [DONE: ...] → final answer
        if (m := re.search(r'\[DONE:\s*(.*?)\]', result, re.DOTALL)):
            return AgentResult(self.agent_type, task, m.group(1).strip(), ...)

        # [TOOL: ...] → execute, feed result back, keep looping
        if (tool_result := self._execute_tool(result)):
            self.messages.append({"role": "assistant", "content": result})
            self.messages.append({"role": "user", "content": tool_result})
            continue

        return AgentResult(..., result, ...)  # plain answer, no tool
GitHub ↗

Runs in your terminal — pip install -r requirements.txt then python src/run.py. Works with a free Groq key out of the box; Gemini, Mistral, OpenAI, and local Ollama are optional fallbacks.

Description

What it does: Pixel Assistant is a modular AI assistant for the command line — notes, todos, timers, calendar, voice, file generation, and dozens of utility commands. Its defining feature is autonomy: any sufficiently complex prompt is auto-routed to an agent without an explicit command, and agents can recursively spawn sub-agents to break a hard task into pieces.

Self-extending: The assistant can write its own skills. /update skill <description> prompts an LLM to generate a standalone, syntax-verified skill module in src/skills/ and auto-registers it — no restart needed. It can also self-debug and self-upgrade its own source.

How it was built: Pure Python. The agent system uses a ReAct-style tool loop (the model emits [TOOL: args], the loop executes it and feeds the result back) rather than a provider-specific function-calling API, so the exact same agent runs on any of the five providers. Cross-platform wrappers live in a single platform.py so it behaves on Windows, macOS, and Linux. A Textual TUI and a FastAPI web UI sit on top of the same core.

Status: Actively developed. Self-hosted — clone and run locally.

How the Agent System Works

  Pixel Assistant — Autonomous Agent Flow
  ═══════════════════════════════════════

      ┌────────────────────┐
      │   User prompt      │
      └─────────┬──────────┘
                │
                ▼
      ┌────────────────────┐   simple (≤5 words / command)
      │   handle_prompt    │ ──────────────────────────────►  direct LLM answer
      │   auto_route()     │
      └─────────┬──────────┘
                │ complex query
                ▼
      ┌────────────────────┐
      │ detect_agent_type  │  explorer · coder · planner
      │                    │  debugger · orchestrator
      └─────────┬──────────┘
                │
                ▼
   ┌───────────────────────────────────────────┐
   │            ReAct Tool Loop                 │
   │                                            │
   │   LLM ──► [TOOL: args] ──► execute ──┐     │
   │    ▲                                 │     │
   │    └───────── result fed back ◄──────┘     │
   │                                            │
   │   tools: SEARCH FETCH READ WRITE RUN       │
   │          GLOB GREP SPAWN DONE              │
   └──────────────────┬────────────────────────┘
                      │ [SPAWN: <type> <task>]
                      ▼
            ┌───────────────────┐
            │   Sub-agent       │  (own context, depth +1)
            │   recursive run   │  returns [SPAWN RESULT]
            └───────────────────┘
                      │
                      ▼
              [DONE: final answer]

  Guards: max turns · max depth · max sub-agents · wall-clock timeout · kill switch
Every agent shares one provider-agnostic tool loop; SPAWN makes delegation recursive.

Dev Notes

Hardest Part

Making delegation safe. Recursive SPAWN can fan out forever, so the loop is fenced by max depth, a max sub-agent count, a hard wall-clock timeout, and a kill switch that any caller can flip mid-run.

Key Decision

Use a text-based ReAct loop instead of vendor function-calling. The model just writes [TOOL: …], so the identical agent works across Groq, Gemini, Mistral, OpenAI, and Ollama — and degrades gracefully when a provider rate-limits.

What's Next

Persistent agent memory across calls, a sub-agent progress tree in the web UI, and per-agent-type model selection so cheap agents use the fast model and planners use the smart one.