Photo Agents
A local Python runtime for screen-aware LLM automation with layered memory and tool execution.
- Source repo
- jmerelnyc/Photo-agents
- Stars
- ★ 655
- Last updated
- 4mo ago
- License
- MIT
- Primary language
- Python
- FA score
- 39/100 · Major gaps
At a glance
- How it runs
- Works with
- Universal · cross-platformOpenAI API · Claude API
- Cost
- Free software; you pay for model usage
- Setup effort
- Medium · a few setup steps
- You'll need
- Typical use
- A developer who wants a tool-calling LLM to identify the largest files in the current directory can run a one-shot file-I/O task.
- Not a fit if
- Users unwilling to send screen data to their chosen LLM provider
- Production teams needing stable APIs before the beta ends
- Source review
- 39/100 · Major gaps 2 safety controls not found
What does this agent do, and when should you use it?
Photo Agents is a locally run Python package for photo-aware agents that operate a computer through a perceive, reason, and act loop. Its runtime combines a streaming agent loop, multi-provider LLM routing, file I/O, sandboxed code execution, browser automation, and layered memory. It documents native paths for Anthropic Claude and OpenAI GPT, plus a mixin failover session. The repository offers a terminal REPL, one-shot task execution, reflect/watchdog mode, and Streamlit, PyQt, and chat-platform clients. A remotely validated Photo Agents API key is required, while memory, skills, and session archives are kept in local directories.
When started with python -m photoagents, the core agent loop drives a tool-calling LLM through a perceive → reason → act cycle. It can perform file I/O, run sandboxed Python, PowerShell, or bash code, and automate a browser through a Chrome DevTools Protocol bridge. The runtime stores working memory, global memory, SOPs, and session archives in layers, and keeps a skill/SOP search vector index under ~/.photoagents/skill_index/. photoagents/evolution/scheduler.py supports reflect/watchdog mode, where a check() function triggers the next task; Langfuse observability and cron-style scheduling are optional components.
- A developer who wants a tool-calling LLM to identify the largest files in the current directory can run a one-shot file-I/O task.
- A user automating work from visible browser state can use the Chrome DevTools Protocol bridge-based browser tooling.
- An individual who needs persistent facts, SOPs, and raw session histories for recurring automation can use the local layered memory under
~/.photoagents/. - A team choosing between terminal, Streamlit web, and PyQt desktop interaction can launch the matching client.
- An automation maintainer who wants follow-on tasks triggered by a
check()condition can use reflect/watchdog mode.
How do you install or deploy this agent?
Python 3.10 or newer is required. Install with pip install photoagents; for all optional clients and integrations, use pip install "photoagents[all]". Set PHOTOAGENTS_API_KEY=pk_live_..., or save the key as api_key in ~/.photoagents/config.json; the first run can also prompt interactively. From the repository root, run cp photoagents/config/keys_template.py credentials.py, then edit credentials.py and enable one provider configuration. A credentials.json file with the same shape is also accepted.
How do you use this agent?
Configure the API key and LLM credentials first. Start the interactive terminal REPL with python -m photoagents. Run a single task with python -m photoagents --task my_task --input "List the largest files in this directory.". Start reflect/watchdog mode with python -m photoagents --reflect photoagents/evolution/scheduler.py. Optional clients include python -m photoagents.clients.desktop_app and pythonw -m photoagents.cli.launcher.
What are this agent's strengths and limitations?
- Combines a streaming agent loop, file operations, code execution, browser automation, and layered memory in one Python runtime.
- Documents native support for Anthropic Claude and OpenAI GPT, with a mixin failover session.
- Keeps memory, session archives, and skill indexing locally under
~/.photoagents/, which supports persistent local state. - Provides terminal, web, desktop, and several chat-platform client options rather than one interaction surface.
- Every service launch depends on a remotely validated Photo Agents API key; a missing or revoked key prevents startup.
- The agent loop requires a network-reachable LLM provider, so it cannot run fully offline.
- Browser tooling depends on
beautifulsoup4and CDP bridge configuration underresources/tmwd_cdp_bridge/. - The project is beta, and its APIs may change before version 1.0.
How does this agent compare with similar options?
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| Photo Agents This agent | 39 · Major gaps | CLIFree + model costs | ★ 655 | 4mo ago | Python | OpenAI API · Claude API |
| Taskhomie | 20 · Major gaps | Desktop appFree + model costs | ★ 711 | 2mo ago | Rust | Claude API |
| Obscura Headless Browser | 75 · Good | CLIFree | ★ 30k | 1d ago | Rust | Claude.ai |
| Opensteer | 49 · Major gaps | CLIFree | ★ 205 | today | TypeScript | — |
How does FollowAgents rate this agent?
Why each dimension lost points
Evidence: README claims local operation and data sent only to LLM provider and license endpoint, but no code-level verification; API key gating exists, but least privilege not detailed; toolset includes file I/O, code execution, browser automation, but no user confirmation mechanism; dependencies listed, but no vulnerability scanning or locked versions; external effects (file modifications, network) not explicitly restricted; rollback not mentioned; source attribution via author info only, unverified. Deductions: lack of user confirmation, rollback, least privilege details.
Evidence: README and pyproject.toml descriptions consistent, but code not reviewed; dependencies listed, but no locked versions or integrity checks; failure messages only mention API key and browser tools, not covering other failures. Deductions: dependency availability unverified, failure messages incomplete.
Evidence: README clearly identifies target users (developers) and multiple usage scenarios (REPL, file I/O, reflect mode, GUI clients); capability boundaries partially described (toolset), but not explicit limits; trigger precision (task input) has examples, but not detailed; environment fit (Windows/macOS/Linux) declared. Deductions: capability boundaries and trigger precision not detailed enough.
Evidence: README structure clear, includes install, run, GUI clients, troubleshooting, FAQ; install notes detailed; naming stable (package name photoagents); examples and FAQ present; known limitations only mention beta status; MIT license explicit; version 0.1.1, but no CHANGELOG file; maintenance responsibility by team, but unverified. Deductions: no CHANGELOG, known limitations insufficient.
Evidence: Output usability (REPL, file I/O) described, but no actual output examples; marginal value (self-evolving, vision memory) innovative, but unverified; cost-benefit (local run, API key) mentioned, but not quantified. Deductions: lack of actual output examples and cost data.
Evidence: README claims (local run, data flow) not backed by code-level evidence; cross-source corroboration limited (only README and pyproject); facts and inferences not clearly separated. Deductions: lack of traceable code evidence and cross-source verification.
- Not found in source: confirmation before actingTurn on (or add) a confirmation step before it acts, and try it in a sandbox or test environment before real data.
- Not found in source: rollback or recovery pathBack up first, or work on a git branch or snapshot, so its changes can be undone.
- This repository is in beta, APIs may change, use with caution in production.
- API key gating relies on remote validation, posing a single point of failure risk.
- Toolset includes code execution and browser automation, ensure controlled environment.
- Dependencies are not version-locked, posing supply chain risk.