[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-80754":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":10,"language":11,"languages":10,"totalLinesOfCode":10,"stars":12,"forks":13,"watchers":14,"openIssues":13,"contributorsCount":13,"subscribersCount":13,"size":13,"stars1d":13,"stars7d":15,"stars30d":15,"stars90d":13,"forks30d":13,"starsTrendScore":13,"compositeScore":16,"rankGlobal":10,"rankLanguage":10,"license":10,"archived":17,"fork":17,"defaultBranch":18,"hasWiki":19,"hasPages":17,"topics":20,"createdAt":10,"pushedAt":10,"updatedAt":29,"readmeContent":30,"aiSummary":31,"trendingCount":13,"starSnapshotCount":13,"syncStatus":32,"lastSyncTime":33,"discoverSource":34},80754,"aura-agent","erickong\u002Faura-agent","erickong","Goal-Driven agent for long-running tasks, docker-isolated workers, intelligent task decomposition, and autonomous execution","",null,"Python",42,0,41,1,37.6,false,"main",true,[21,22,23,24,25,26,27,28],"ai-agent","autonomous-agent","deepseek","developer-tools","docker","llm-agents","python","task-orchestration","2026-06-12 04:01:29","# Aura Agent\r\n\r\n![Aura Dashboard](.\u002Fdashboard.png)\r\n\r\n**Aura** is an autonomous task orchestrator designed for ambitious, long-running projects that demand deep multi-faceted exploration — automatically decomposing complex goals into concrete subtasks, routing them to Pro or Flash Layer 2 workers, and continuously verifying results against acceptance criteria over hours or days of autonomous operation. It supports secure Docker-based execution, flexible API configuration, and multiple worker backends such as `Claude Code`, `Qwen Code`, `Codex CLI`, `ds_code`, and `OpenCode`.\r\n\r\n---\r\n\r\n## Architecture\r\n\r\n![Aura Architecture Overview](.\u002Faura_architecture.png)\r\n\r\n---\r\n\r\n## Quick Start (Under 2 Minutes)\r\n\r\n```bash\r\ngit clone https:\u002F\u002Fgithub.com\u002Ferickong\u002Faura-agent\r\ncd aura-agent\r\npython -m pip install -e .\r\n\r\n# Run interactive setup to configure API keys and models\r\naura setup\r\n\r\n# Go to your project\r\ncd \u002Fpath\u002Fto\u002Fyour\u002Fproject\r\n\r\n# Create your task file (task.md for example), describe your goal.\r\n# Aura your goal\r\naura start --task-file task.md\r\n```\r\n\r\nEdit `task.md` anytime while Aura is running. The agent detects changes, replans, and continues work automatically.\r\n\r\nBy default Aura starts with the Rich terminal dashboard. Use `--no-ui` for plain command-line output:\r\n\r\n```bash\r\naura start --task-file task.md --no-ui\r\n```\r\n\r\nIf Docker is enabled in your config but you want to run workers locally for one session:\r\n\r\n```bash\r\naura start --task-file task.md --no-docker\r\n```\r\n\r\nChoose a worker delegation mode per run:\r\n\r\n```bash\r\naura start --task-file task.md --worker-mode auto\r\naura start --task-file task.md --worker-mode flash-first\r\n\r\n# Use local Codex CLI as the Pro worker for this run\r\naura task.md --workerpro-codex\r\naura start --task-file task.md --worker-mode pro-only\r\n```\r\n\r\n### Installation Notes\r\n\r\nAura does not pin a package index. `python -m pip install -e .` uses the user's local pip configuration, such as PyPI, a corporate mirror, or a regional mirror.\r\n\r\nIf editable install fails while installing build dependencies such as `setuptools` or `wheel`, the configured package index may be incomplete or unreachable. Use a working index, for example:\r\n\r\n```bash\r\npython -m pip install -e . --index-url https:\u002F\u002Fpypi.org\u002Fsimple\r\n```\r\n\r\nIf `setuptools` and `wheel` are already installed in the environment, this can also avoid downloading isolated build dependencies:\r\n\r\n```bash\r\npython -m pip install -e . --no-build-isolation\r\n```\r\n\r\n---\r\n\r\n## Pro \u002F Flash Workers\r\n\r\nAura can use two independent Layer 2 worker roles:\r\n\r\n| Worker | Purpose | Typical backend |\r\n| ------ | ------- | --------------- |\r\n| Pro | Rare expert path for very hard, long-context, high-risk, proof-heavy, or architecture-level tasks | Claude Opus\u002FSonnet, DeepSeek Pro |\r\n| Flash | Default path for ordinary bounded work: simple and medium coding, debugging, scripts, focused analysis, tests, and normal docs | Qwen Coder, Claude Haiku |\r\n\r\nThe intended default is economical: use Flash for most clear, bounded tasks, and reserve Pro for tasks where the main risk is reasoning quality rather than execution effort. Modern Flash models can be strong; they are not only for trivial chores.\r\n\r\nWorker modes:\r\n\r\n| Mode | Behavior |\r\n| ---- | -------- |\r\n| `pro-only` | Everything goes to Pro. |\r\n| `auto` | Aura routes ordinary bounded tasks to Flash and genuinely hard tasks to Pro. |\r\n| `flash-first` | Aura tries Flash first and escalates to Pro only after a clear model-capability failure. |\r\n| `flash-only` | Everything goes to Flash. |\r\n\r\nPro and Flash are configured separately: backend, API key, base URL, and model do not interfere with each other. For example, Pro can use `claude` while Flash uses `qwencode`.\r\n\r\nFor a one-off non-Docker run with your already configured local Codex CLI, pass `--workerpro-codex`. Aura will use Codex as the Pro worker and print the Codex model detected from `~\u002F.codex\u002Fconfig.toml` at startup. If your config enables Docker workers, add `--no-docker`; otherwise Aura will stop with a clear error because local Codex is not a Docker worker backend.\r\n\r\nImportant: a Flash worker still needs real tool capability. It must be able to read\u002Fwrite files, run commands, use the project workspace, and produce final artifacts through its CLI backend. A cheap model without basic coding-agent tools is not a useful Flash worker for Aura.\r\n\r\nFor Qwen Code workers, Aura sets `QWEN_CODE_MAX_OUTPUT_TOKENS` from `AURA_QWENCODE_MAX_OUTPUT_TOKENS` (default `25000`). This avoids OpenAI-compatible servers such as vLLM rejecting requests because Qwen Code reserves a 32K\u002F64K output budget on top of an already long prompt.\r\n\r\n---\r\n\r\n## Docker Isolation (Optional)\r\n\r\nWhen enabled, Aura runs Layer 2 workers in Docker:\r\n\r\n* Each worker runs in a separate container with a clean `\u002Fworkspace`.\r\n* Non-root user prevents host file or system access.\r\n* Resource limits (CPU, memory, GPU) ensure rogue processes stay contained.\r\n* Pre-built image automatically pulled from GHCR.\r\n\r\nConfiguration in `.env` or via `aura setup`:\r\n\r\n```text\r\nAURA_WORKER_MODE=auto\r\nAURA_PRO_BACKEND=claude\r\nAURA_PRO_API_KEY=\u003Cpro-key>\r\nAURA_PRO_BASE_URL=\u003Cpro-base-url>\r\nAURA_PRO_MODEL=\u003Cpro-model>\r\nAURA_FLASH_BACKEND=qwencode\r\nAURA_FLASH_API_KEY=\u003Cflash-key>\r\nAURA_FLASH_BASE_URL=\u003Cflash-base-url>\r\nAURA_FLASH_MODEL=\u003Cflash-model>\r\nAURA_WORKERS_IN_DOCKER=1\r\nAURA_DOCKER_BIN=docker\r\nAURA_DOCKER_GPUS=all\r\nAURA_DOCKER_EXTRA_ARGS=\r\n```\r\n\r\nDocker GPU access is controlled by `AURA_DOCKER_GPUS`:\r\n\r\n| Value | Effect |\r\n| ----- | ------ |\r\n| empty | Do not pass GPU access to Docker. CPU-only worker containers. |\r\n| `all` | Pass all visible GPUs to worker containers (`docker run --gpus all`). |\r\n| `device=0` | Pass only GPU 0. Other Docker `--gpus` values are also accepted. |\r\n\r\nFor finer control, `AURA_WORKER_CUDA_VISIBLE_DEVICES` sets `CUDA_VISIBLE_DEVICES` inside workers, while `AURA_WORKER_MAX_GPU_UTIL_PERCENT`, `AURA_WORKER_MAX_GPU_MEMORY_PERCENT`, and related resource settings control Aura's worker guard.\r\n\r\n### Docker Image\r\n\r\nThe default image is `ghcr.io\u002Ferickong\u002Faura-claude-cuda:latest`. Aura pulls it automatically on first use.\r\n\r\n**If the automatic pull fails** (e.g., network issues, registry rate limits), pull it manually:\r\n\r\n```bash\r\ndocker pull --platform linux\u002Famd64 ghcr.io\u002Ferickong\u002Faura-claude-cuda:latest\r\n```\r\n\r\n### Rebuilding with Custom Packages\r\n\r\nTo add your own Python or system packages to the Docker image, use the files in [docker_scripts\u002F](.\u002Fdocker_scripts\u002F):\r\n\r\n1. Edit `docker_scripts\u002Frequirements.txt` to add your pip packages.\r\n2. Edit `docker_scripts\u002FDockerfile` to add system packages or other dependencies.\r\n3. Rebuild the image:\r\n\r\n```bash\r\n# Linux \u002F macOS\r\nbash docker_scripts\u002Frebuild.sh\r\n\r\n# Windows PowerShell\r\npowershell -File docker_scripts\u002Frebuild.ps1\r\n```\r\n\r\nThe rebuild scripts tag the image as `ghcr.io\u002Ferickong\u002Faura-claude-cuda:latest` locally, which Aura will use instead of pulling from the registry.\r\n\r\n---\r\n\r\n## Comparison with Other Agents\r\n\r\n| Dimension           | Codex Goal                              | Aura Agent                                | GitHub Copilot Cloud Agent                  | Claude Chat                      |\r\n| ------------------- | --------------------------------------- | ----------------------------------------- | ------------------------------------------- | -------------------------------- |\r\n| **System level**    | Inside Codex                            | Above coding agents                       | Inside GitHub                               | General assistant                |\r\n| **Task unit**       | One durable goal                        | Markdown goal → task tree                 | Issue \u002F prompt → branch or PR               | Chat prompt                      |\r\n| **Execution style** | Keep working until verifiable end state | Orchestrator spawns bounded workers       | Cloud agent edits branch and can open PR    | Interactive reasoning            |\r\n| **Parallelism**     | Limited                                 | Explicit Layer 2 workers                  | Multiple sessions possible, but PR-centered | None by default                  |\r\n| **Verification**    | Tests, logs, artifacts, benchmarks      | Evidence from artifacts\u002Flogs\u002Fresult files | Diff, commits, tests, PR review             | User review                      |\r\n| **Best fit**        | Focused repo work                       | Long-horizon autonomous projects          | Team software workflow                      | Thinking, drafting, analysis     |\r\n\r\n---\r\n\r\n## Example Use Cases\r\n\r\n* Build a quantitative trading pipeline from scratch, testing multiple models until target Sharpe ratio is achieved.\r\n* Generate research reports, whitepapers, or documentation automatically.\r\n* Automate repetitive coding or data processing tasks with minimal supervision.\r\n\r\n---\r\n\r\n## FAQ \u002F Common Issues\r\n\r\n### Docker image pull fails (all workers blocked or failed)\r\n\r\nIf workers won't start and logs show Docker pull failures:\r\n\r\n```bash\r\n# Manually pull the image\r\ndocker pull --platform linux\u002Famd64 ghcr.io\u002Ferickong\u002Faura-claude-cuda:latest\r\n\r\n# Or run without Docker entirely\r\naura start --task-file task.md --no-docker\r\n```\r\n\r\nThis is the most common cause of \"all task nodes blocked or failed\" — the orchestrator retries spawns but the image never becomes available. After a pull failure, Aura auto-falls back to local mode for the rest of the session.\r\n\r\n### Docker not installed (macOS \u002F Linux)\r\n\r\nmacOS does not ship with Docker. Install [Docker Desktop](https:\u002F\u002Fwww.docker.com\u002Fproducts\u002Fdocker-desktop\u002F) or use `--no-docker` to run workers locally:\r\n\r\n```bash\r\naura start --task-file task.md --no-docker\r\n```\r\n\r\nTo permanently disable Docker, set in `.env`:\r\n\r\n```text\r\nAURA_WORKERS_IN_DOCKER=0\r\n```\r\n\r\n### macOS Terminal rendering glitches\r\n\r\nmacOS Terminal.app may not render the Rich dashboard correctly. Aura defaults to plain mode on macOS. If you want to try the dashboard, use a modern terminal (iTerm2, Warp, Kitty) and force Rich mode:\r\n\r\n```bash\r\naura start --task-file task.md --ui rich\r\n```\r\n\r\n### API connection errors\r\n\r\nIf Aura cannot reach the LLM API, re-run interactive setup to configure endpoints and keys:\r\n\r\n```bash\r\naura setup\r\n```\r\n\r\nCommon checks:\r\n- `AURA_API_BASE_URL` ends with `\u002Fanthropic` for DeepSeek-compatible proxies\r\n- `AURA_API_KEY` is the correct API key for the configured endpoint\r\n- `AURA_API_MODEL` matches a model available on the configured endpoint\r\n\r\n### Workers spawn but do nothing (stuck at 0% CPU)\r\n\r\nThis is usually a config or environment issue inside the worker. Check:\r\n- The configured Pro\u002FFlash backend CLI is installed (`claude`, `qwen`, `ds-code`, `opencode`, or `codex`)\r\n- `AURA_PRO_BACKEND` \u002F `AURA_FLASH_BACKEND` matches an installed CLI\r\n- The worker API key, base URL, and model are reachable\r\n- For Flash workers: the backend must still support basic agent tools such as file reads\u002Fwrites and command execution\r\n\r\n### Verbose logging\r\n\r\nTo see more detail about what Aura is doing, check the state files:\r\n\r\n```bash\r\n# Decision log — every status change with reasons\r\ncat .aura\u002F\u003Cproject>\u002Fstate\u002Fdecision_log.json\r\n\r\n# Full prompt sent to the LLM each cycle\r\ncat .aura\u002F\u003Cproject>\u002Fstate\u002Fcurrent_prompt.md\r\n\r\n# Progress report with task tree and token stats\r\ncat .aura\u002F\u003Cproject>\u002Fstate\u002Fprogress.md\r\n```\r\n\r\n---\r\n\r\n## Topics \u002F Tags (GitHub)\r\n\r\n`ai-agents`, `coding-agent`, `deepseek`, `docker`, `autonomous-agents`, `Claude`, `OpenCode`, `ds_code`\r\n\r\n---\r\n","Aura Agent 是一个面向长期运行任务的自主任务编排器，能够将复杂目标智能分解为具体子任务，并通过Docker隔离的工作者进行自动执行。其核心功能包括支持安全的Docker环境执行、灵活的API配置以及多种后端工作者如Claude Code、Qwen Code等。技术上，Aura利用了先进的AI代理技术来实现任务的自主规划与验证。适合需要长时间运行且涉及多方面深入探索的项目场景使用，尤其是在软件开发、代码调试和文档生成等领域。",2,"2026-06-11 04:01:53","CREATED_QUERY"]