Intent Agent

AI-powered CLI agent that controls your desktop with natural language commands.

Features

• Natural Language Control: Control your desktop with simple English commands
• Interactive REPL: Continuous command mode for multiple operations
• Screenshot Analysis: Capture and analyze screen content for context
• Secure Execution: Sandboxed code execution with dangerous pattern blocking
• Authentication: Secure PKCE-based login with Intent Web Dashboard
• Cross-Platform: Works on macOS, Windows, and Linux

Installation

From PyPI (recommended)

pip install intent-agent

From source

git clone https://github.com/intent-cli/intent-cli.git
cd intent-cli
pip install -e .

Quick Start

1. Install and authenticate:

pip install intent-agent
intent login

2. Enter interactive mode:

intent

3. Try a command:

intent> open calculator
intent> click the start button
intent> take a screenshot

Usage

Interactive Mode

Start the interactive command mode by running intent without arguments:

intent

Available Commands

• help or h - Show help message
• status - Show authentication status and credits
• logout - Log out and clear stored credentials
• exit or quit - Exit interactive mode
• Any natural language command - Execute the command

Direct Command Execution

Execute a command directly without entering interactive mode:

intent "open calculator"
intent "click the settings button"
intent "take a screenshot"

Command Options

• -v, --verbose - Enable verbose output
• -c, --confirm - Require confirmation before execution
• -d, --dry-run - Generate code without executing it

How It Works

Intent CLI uses a secure code execution engine:

1. Your natural language command is sent to the Intent AI API
2. The AI generates Python code to perform the action
3. The code is validated for safety (blocked imports, syntax checks)
4. If safe, the code is executed in a sandboxed environment
5. Results are captured and displayed

Security

Intent blocks execution of potentially dangerous code:

• os, subprocess, pathlib - File system operations
• open - File reading/writing
• eval, exec - Dynamic code execution
• import statements for unsafe modules

Safe operations like pyautogui (mouse/keyboard control) and Pillow (image processing) are allowed.

Configuration

Intent CLI uses environment variables for configuration. Copy .env.example to .env:

cp .env.example .env

Environment Variables

Development

Clone the repository and install dependencies:

git clone https://github.com/intent-cli/intent-cli.git
cd intent-cli
pip install -e ".[dev]"

Run tests:

pytest -v

Build the package:

python -m build

Troubleshooting

macOS permissions

For screenshot capture on macOS, you may need to grant Screen Recording permission in System Preferences > Privacy & Security > Screen Recording.

Keyring errors

If you encounter keyring-related errors on Linux, install the keyring backend:

pip install keyrings.alt

License

MIT License - see LICENSE file for details.