Agent Control
Start, stop, and monitor the background CLI agent process in the AssistMe Desktop App.
Overview
The Agent Control page lets you manage the AssistMe CLI agent that runs as a background process on your computer. This agent is the engine behind all task execution — it receives your prompts from the Cowork workspace, uses tools (browser automation, code execution, web search), and returns results.
Why a Background Agent?
Unlike the mobile app or web dashboard that rely on cloud-hosted agents, the Desktop App runs an agent locally on your machine. This enables:
- File system access — The agent can read, write, and manage files in your local workspace
- Local code execution — Run scripts and programs directly on your computer
- Browser automation — Control a local browser for web scraping, form filling, and more
- Credential access — Use locally stored API keys and secrets during task execution
- Lower latency — No round-trip to a remote server for local operations
Agent Status
The Agent page displays a real-time status indicator:
| Status | Indicator | Meaning |
|---|---|---|
| Stopped | Gray | Agent is not running |
| Starting | Yellow | Agent process is launching |
| Running | Green | Agent is ready to accept tasks |
| Error | Red | Agent encountered a problem |
Starting the Agent
Click the "Start Agent" button to launch the CLI agent. The agent:
- Checks for CLI updates — Ensures the latest AssistMe CLI version is installed
- Spawns the process — Starts
assistmeas a child process with your authentication token - Monitors readiness — Watches for startup signals (session creation, heartbeat)
- Transitions to Running — Once ready, the status changes to green
On first login, the agent starts automatically. You can configure this behavior in settings.
Workspace Directory
The agent runs in a configurable workspace directory. This is the root directory the agent has access to for file operations. By default, it uses your home directory or a designated workspace path.
Stopping the Agent
Click the "Stop Agent" button to shut down the agent gracefully:
- SIGTERM is sent to the agent process
- The agent has 5 seconds to clean up and exit
- If the agent doesn't exit in time, SIGKILL is used as a last resort
Stopping the agent cancels any in-progress tasks. The agent can be restarted at any time.
Real-Time Logs
The Agent page shows a live log feed of the agent's stdout and stderr output:
| Log Type | Color | Content |
|---|---|---|
| stdout | Green | Normal agent output — task progress, tool results |
| stderr | Red | Errors and warnings |
| status | Blue | System messages — agent state changes |
Log Buffer
The Desktop App maintains a ring buffer of 5,000 log entries in the main process. This means:
- Logs survive if you navigate away from the Agent page and come back
- Logs survive if the renderer process refreshes
- Older logs are automatically discarded when the buffer fills
Clearing Logs
Click the "Clear Logs" button to reset the log display. This clears the visual log output but doesn't affect the agent's operation.
How the Agent Connects
The background agent communicates with the AssistMe cloud via:
- Authentication — Uses your
ASSISTME_TOKEN(injected automatically from your session) - Heartbeat — Sends periodic heartbeat signals so the cloud knows the agent is alive
- Task Polling — Checks for new tasks assigned to your session
- Result Reporting — Sends task results, tool outputs, and screenshots back to the cloud
The Cowork Workspace and the web dashboard's Sessions page both display the status of your connected agent.
CLI Version Management
The Desktop App manages CLI versions automatically:
- On agent start, it checks if a newer CLI version is available
- Auto-upgrades the CLI via npm if an update is found
- Minimum Node.js requirement: v18+ (checked during setup)
You generally don't need to manage CLI versions manually — the Desktop App handles it.
Troubleshooting
Agent Stuck on "Starting"
The agent auto-promotes from "Starting" to "Running" after a timeout if no explicit readiness signal is detected. If it remains stuck:
- Check the log output for errors (red text)
- Verify your internet connection
- Try stopping and restarting the agent
Agent Shows "Error" Status
Common causes:
- Authentication expired — Sign out and sign back in
- Port conflict — Another process may be using the same port
- Missing dependencies — Re-run the Setup Wizard from Settings
No Tasks Being Processed
- Ensure the agent status is Running (green)
- Check the Cowork Workspace to verify tasks are being sent
- Verify the web dashboard's Sessions page shows your session as "Online"
Next Steps
- Cowork Workspace — Send tasks to the running agent
- Desktop Tools — Manage Skills, Jobs, Programs, and Credentials
- Web Dashboard Sessions — Monitor agent sessions from the web