Metadata-Version: 2.4
Name: pat-agent
Version: 0.1.5
Summary: PAT — an AI coding agent built from scratch.
License-Expression: MIT
Project-URL: Homepage, https://github.com/p2ratik/Pat-Code
Project-URL: Repository, https://github.com/p2ratik/Pat-Code
Project-URL: Issues, https://github.com/p2ratik/Pat-Code/issues
Keywords: ai,agent,llm,cli,automation,coding-agent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Operating System :: OS Independent
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: openai>=1.0.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: rich>=13.0.0
Requires-Dist: click>=8.0.0
Requires-Dist: keyring>=24.0.0
Requires-Dist: platformdirs>=4.0.0
Requires-Dist: tiktoken>=0.7.0
Requires-Dist: fastmcp>=2.0.0
Requires-Dist: ddgs>=9.0.0
Requires-Dist: tomli>=2.0.0; python_version < "3.11"
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"

# PAT Agent

PAT Agent is a smart command-line assistant that can help you work with files, run commands, search code, and automate repetitive tasks.

It is designed to be easy to use, even if you are not a programmer.

## Why People Use PAT

- It can read and edit files for you.
- It can run terminal commands safely.
- It can connect to external tools through MCP servers (including OAuth2 providers like Google Workspace).
- It can run specialized mini-agents called subagents.
- It plans, reasons, and verifies steps for higher accuracy in complex tasks.
- It uses embedding-based memory so recall is fast and relevant.

## 5-Minute Quick Demo

This section is for first-time users.

### 1) Install

```bash
pip install pat-agent 
```

After installation, the CLI command is:

```bash
pat-agent
```

### 2) Configure API Key and Base URL

```bash
pat-agent configure apikey YOUR_API_KEY
pat-agent configure baseurl YOUR_BASE_URL
```

Pat supports 3 Base urls :
1. Open router : https://openrouter.ai/api/v1
2. Openapi : https://api.openai.com/v1
3. Gemini : https://generativelanguage.googleapis.com/v1beta/openai/

Check what is configured:

```bash
pat-agent configure show
```

### 3) Start the Agent

```bash
pat-agent init 
pat-agent
```

You can now type plain English requests, for example:

- List all Python files in this project.
- Create a new README section for troubleshooting.
- Search for where session data is saved.

### 4) Run One Prompt and Exit (Optional)

```bash
pat-agent --prompt "Summarize this project in simple words"
```

## Screenshot / Demo Image

![PAT Demo](https://raw.githubusercontent.com/p2ratik/Pat-Code/master/Pat-Code/assets/image.png)


## Commands You Will Use Most

### Main Command

```bash
pat-agent [--prompt "..."] [--cwd PATH]
```

- `--prompt` or `-p`: run once and exit.
- `--cwd` or `-c`: run PAT in a specific folder.

### Configure Commands

```bash
pat-agent configure apikey VALUE
pat-agent configure baseurl VALUE
pat-agent configure show
pat-agent configure delete apikey
pat-agent configure delete baseurl
```

What each one does:

- `configure apikey`: saves your API key securely in OS keyring.
- `configure baseurl`: saves API endpoint URL securely in OS keyring.
- `configure show`: shows current configured values (API key is masked).
- `configure delete`: removes a saved value.

## Interactive Commands (Inside PAT)

When PAT is running, type these commands:

- `/help` : show help.
- `/clear` : clear current conversation.
- `/config` : show current active settings.
- `/model <name>` : switch model for this session.
- `/approval <policy>` : change safety approval mode.
- `/tools` : list available tools.
- `/mcp` : show MCP server status.
- `/stats` : show session stats.
- `/save` : save current session.
- `/sessions` : list saved sessions.
- `/resume <session_id>` : resume a saved session.
- `/checkpoint` : create a checkpoint.
- `/listcheckpoints` : list checkpoints.
- `/restore <checkpoint_id>` : restore a checkpoint.
- `/exit` or `/quit` : close PAT.

## Configuration System (Simple Explanation)

PAT loads settings from two places:

1. Global config on your machine.
2. Project config in your project folder.

Project config has higher priority.

### Config File Name

- `config.toml`

### Project Config Location

- `.ai-agent/config.toml` inside your project

### Example Config (Safe Starting Point)

```toml
max_turns = 100
approval = "on-request"

[model]
name = "claude-opus-4.7"
temperature = 1.0
context_window = 256000

[shell_environment]
ignore_default_excludes = false
exclude_patterns = ["*KEY*", "*TOKEN*", "*SECRET*"]
```

## How PAT Handles API Key and Base URL

PAT checks credentials in this order:

1. OS keyring (recommended)
2. Environment variables

Environment variable fallback names:

- `API_KEY`
- `BASE_URL`

## Tools, MCP, and Subagents

### Built-in Tools

PAT includes built-in tools for:

- File reading and writing
- File editing
- Directory listing
- Pattern search and glob search
- Shell commands
- Web search and web fetch
- Memory and todo tracking
- Multi-file patch application

### MCP Support

PAT can connect to MCP servers from config and auto-load their tools.
OAuth2-based MCP connections are supported for providers like Google Workspace.

MCP tool names are registered in this format:

- `server_name__tool_name`

### Configure MCP Servers (Quick Guide)

Add MCP servers to your project config at `.ai-agent/config.toml`.

HTTP/SSE MCP server with OAuth2:

```toml
[mcp_servers.google_workspace]
url = "https://your-mcp.example.com"

[mcp_servers.google_workspace.oauth]
client_id = "YOUR_CLIENT_ID"
client_secret = "YOUR_CLIENT_SECRET"
scopes = ["https://www.googleapis.com/auth/drive.readonly"]
```

Notes:
- If you omit `client_id` and `client_secret`, PAT uses the MCP server's OAuth discovery flow (browser consent).
- You can use `auth_token` instead of `oauth` for non-OAuth servers.
- For local stdio MCP servers, use `command` and `args` instead of `url`.

Example stdio MCP server:

```toml
[mcp_servers.local_files]
command = "node"
args = ["server.js"]
```

### Subagents

Subagents are focused mini-agents that PAT can call for specific tasks.

Default subagents:

- `subagent_codebase_investigator`
- `subagent_code_reviewer`
- `subagent_dependency_tracer`
- `subagent_root_cause_investigator`
- `subagent_regression_hunter`
- `subagent_architecture_mapper`

You can create your own subagents.

## Create Your Own Subagent

Add this to `.ai-agent/config.toml`:

```toml
[[user_subagents]]
name = "doc_writer"
description = "Writes and improves docs"
goal_prompt = "You are a documentation specialist. Write clear and beginner-friendly docs."
allowed_tools = ["read_file", "glob", "grep", "write_file", "edit"]
max_turns = 20
timeout_seconds = 600
```

Once loaded, the subagent appears as a tool named:

- `subagent_doc_writer`

## Approval Policies (Safety)

Available policies:

- `on-request`
- `on-failure`
- `auto`
- `auto-edit`
- `never`
- `yolo`

If you are new, start with:

- `on-request`

## Plain-Language Architecture

PAT follows a simple flow:

1. You ask something.
2. PAT sends your request + context to the model.
3. The model decides if tools are needed.
4. PAT runs tools (with approval checks if needed).
5. PAT returns the final response.

## Reasoning and Investigation

PAT uses a deliberate problem-solving loop for better accuracy:

- Plans and reasons before acting on non-trivial tasks.
- Verifies results after each major step.
- During debugging or investigation, it builds a system-level understanding first,
  traces dependencies, estimates confidence, and then answers.

## Embedding Memory

PAT stores memory as embeddings so it can search and recall relevant context quickly.
This improves long-running tasks without requiring you to restate details.

This loop continues until the task is done.

## Troubleshooting

- If PAT says API key is missing, run:
  - `pat-agent configure apikey YOUR_API_KEY`
- If PAT cannot reach your provider, check base URL:
  - `pat-agent configure baseurl YOUR_BASE_URL`
- If tools are missing, run `/tools` and verify your config is not restricting them.
- If MCP tools are missing, run `/mcp` and check MCP server config.

## Project Structure (High Level)

```text
Pat-Code/
  main.py
  agent/
  client/
  config/
  context/
  tools/
  safety/
  ui/
```

## License

MIT
