# Agent Design Philosophy Review for AgInTiFlow This review compares local agent projects under `/home/lachlan/ProjectsLFS/Agent` and extracts product and architecture lessons for AgInTiFlow. Raw snapshots are stored in `references/raw/`, generated by `references/run_design_scan.sh`. The practical goal is not to copy every feature. AgInTiFlow should stay a focused website-control and local-tool agent, while borrowing the strongest patterns around operator experience, safety, persistence, provider choice, and workflow design. ## Core Thesis The best agent projects are not just model wrappers. They define an operating model: - how a human gives direction - how the agent plans and executes - how tools are constrained - how state and memory survive across runs - how failures are reviewed and retried - how the product earns trust over time AgInTiFlow should be designed as a local operator console for web and shell tasks, not only as a browser automation demo. ## Claude Code `claude-code` is product-first. Its top-level surface is small: a short README, obvious install flow, examples, plugins, and security notes. It does not ask the user to understand an internal framework before using the tool. Design philosophy: - terminal-native agent use should feel immediate - extension is visible, but not required for first use - the product should optimize for operator flow rather than architectural display - repo structure should make the primary user path easy to find What AgInTiFlow should learn: - keep the README focused on first-run success - make `npm run web` and the browser UI the obvious primary path - expose extensions gradually through a clear `tools/` or provider-adapter surface - keep the default experience simple even if the internal runner becomes more modular What to avoid: - adding plugin complexity before core browser, shell, memory, and sandbox flows are stable ## Codex `codex` is the most disciplined operational repo in the set. The important design lesson is not only the CLI implementation. It is the strict collaboration contract: file editing rules, sandbox expectations, testing discipline, review behavior, and clear limits around destructive actions. Design philosophy: - agent behavior must be constrained by explicit rules - risky actions should require a policy decision before execution - verification is part of the workflow, not an optional afterthought - users should be able to audit what happened What AgInTiFlow should learn: - treat guardrails as architecture, not UI decoration - keep shell commands behind allowlists, sandbox options, and destructive-action checks - persist event logs in a readable format for every run - split tools by risk level: read-only inspection, browser navigation, local mutation, network, and credentials - make error recovery visible in the conversation instead of hiding it in logs What to avoid: - heavy process rules that make simple tasks slower than using a normal terminal ## GitHub Copilot SDK `copilot` is platform-oriented. It is not only an app; it is a reusable SDK surface with language bindings and protocol-level thinking. The repo communicates that the runtime is something other products can embed. Design philosophy: - the agent runtime should be separable from any single UI - protocol contracts matter because integrations depend on them - language and host boundaries should not leak into the core mental model What AgInTiFlow should learn: - keep `runAgent` usable from CLI, web UI, and future API server paths - define stable tool input/output contracts - avoid coupling provider calls directly to DOM rendering - make session storage independent from the interface that created the session What to avoid: - trying to become a multi-language SDK before AgInTiFlow has a mature single-language product ## Gemini CLI `gemini-cli` is adoption-first. It emphasizes direct terminal access, broad automation, large-context work, MCP, docs, tests, evals, and performance checks. It presents itself as useful immediately, then expands into deeper workflows. Design philosophy: - onboarding is part of the product - a CLI can stay approachable while supporting advanced integrations - automated tests and evals are required once the tool becomes broad - automation should be described in user outcomes, not only implementation details What AgInTiFlow should learn: - keep setup copy-paste friendly - explain common tasks: list a folder, summarize a page, search a site, extract links, inspect a repo - add small eval scenarios for browser tasks and shell tasks - keep terminal mode healthy even as the web UI improves - document model/provider setup as a first-class feature What to avoid: - broad feature sprawl before the core execution loop is reliable ## Qwen Code `qwen-code` is provider-aware and ecosystem-aware. It assumes users may want different models and runtimes, and it treats provider choice as a normal product surface rather than an advanced configuration trick. Design philosophy: - model choice is part of the user experience - provider quirks should be isolated behind adapters - local settings should remember what the user prefers - package-level ownership and tests help the project scale What AgInTiFlow should learn: - keep OpenAI and DeepSeek selection visible and persistent - add model presets instead of making users memorize model names - isolate provider-specific request/response quirks in `model-client.js` - store UI preferences and session defaults in SQLite or another durable local store - make future providers like Qwen, Kimi, or local OpenAI-compatible servers easy to add What to avoid: - turning provider support into many scattered `if provider` branches across the codebase ## LazyingArtBot `LazyingArtBot` is a local-first workflow operating system. It combines docs, references, skills, extensions, UI, Docker, scripts, orchestration, and branding. Its repo teaches that operational assets are product assets. Design philosophy: - workflows are more durable than one-off prompts - references, prompts, scripts, and docs should live near the product - local autonomy matters: Docker, hooks, skills, and integrations all support operator control - identity and presentation are part of adoption What AgInTiFlow should learn: - keep `references/` as a design memory and prompt library - document not only code APIs, but actual operator playbooks - make Docker sandboxing a normal option for shell tools - keep logo, README, sponsor metadata, and examples polished - design around repeatable workflows like research, extraction, QA, and local repo inspection What to avoid: - expanding into too many surfaces before the information architecture is easy to navigate ## Claw Code `claw-code` is the clearest philosophy document in the set. Its own `PHILOSOPHY.md` says the codebase is not the main thing to study; the coordination system that produced it is the real lesson. It frames the human as the director and the agents as labor. The human can give a short directive through Discord, walk away, and let coordinated agents plan, execute, review, retry, and push. The repo shape reinforces that philosophy: - `PHILOSOPHY.md` explains the coordination model directly - `USAGE.md` gives task-oriented operating instructions - `PARITY.md` tracks migration and capability parity - `ROADMAP.md` records future work and cleanup - `rust/` is the canonical runtime workspace - `src/` and `tests/` preserve companion/reference surfaces - the Rust workspace has explicit provider, permission, session, plugin, MCP, skills, mock harness, and telemetry layers Design philosophy: - the human interface does not have to be the terminal - notifications and lifecycle routing should live outside the agent context window - multi-agent systems need roles, handoffs, disagreement loops, and verification loops - parity tracking matters when rewriting or porting an agent runtime - the durable bottleneck is not typing speed; it is direction, taste, task decomposition, and judgment What AgInTiFlow should learn: - the chat UI should become a real operator surface, not just a form that starts one run - session continuation should feel like directing ongoing work, not rerunning a script - event logs and run status should be machine-readable so external monitors can notify the user - if major rewrites happen, keep a parity checklist so product behavior does not regress - consider a future lightweight "director mode" where the user gives a goal and AgInTiFlow decomposes browser, shell, and review steps before execution - keep notifications, progress summaries, and long-running task state outside the model prompt where possible What to avoid: - copying the full multi-agent coordination stack before AgInTiFlow needs it - confusing an impressive generated codebase with a trustworthy user-facing workflow ## Cross-Project Patterns Several patterns repeat across the strongest repos: - Strong defaults matter more than many options. - Tool boundaries must be explicit and auditable. - Provider flexibility should not leak into the rest of the application. - Session state is central to the feeling of intelligence. - A good agent product needs both a fast first run and a reliable recovery story. - Docs, prompts, references, and examples are part of the product. - Sandbox and permission design should be built early. - The operator interface can be CLI, web UI, chat, Discord, or IDE, but the runtime should not be trapped inside one interface. ## Recommended AgInTiFlow Direction AgInTiFlow should position itself as a local web-and-shell operator for practical automation: - browser control for websites and dashboards - guarded shell execution for local inspection - Docker sandboxing for safer command runs - persistent settings and session history - provider selection with sensible defaults - readable logs and resumable conversations The next design moves should be: 1. Keep the core runner modular: model client, browser tools, shell tools, sandbox, policy, session store, and web server. 2. Add model presets and provider adapters cleanly. 3. Add small eval tasks for browser and shell behavior. 4. Build a stronger conversation-first UI where the user can continue a run naturally. 5. Add a parity or capability checklist as features grow. 6. Keep references and prompts in version control so product thinking is not lost. ## Product Principle AgInTiFlow should not try to become the largest agent repo. It should become the clearest local operator product: - simple enough to run quickly - structured enough to extend safely - transparent enough to trust - flexible enough to use different models - memorable enough to feel like an AgInTi product The best blend is `Claude Code` simplicity, `Codex` discipline, `Copilot` modularity, `Gemini CLI` onboarding, `Qwen Code` provider flexibility, `LazyingArtBot` workflow memory, and `Claw Code` human-directed coordination philosophy.