{"id":24812886,"url":"https://github.com/agiunderground/useless-agent","last_synced_at":"2026-03-07T07:01:53.610Z","repository":{"id":274158135,"uuid":"921922970","full_name":"agiUnderground/useless-agent","owner":"agiUnderground","description":"A little proof-of-concept agent that uses text-only LLMs to navigate Linux desktop","archived":false,"fork":false,"pushed_at":"2026-03-01T09:35:38.000Z","size":20890,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2026-03-01T13:18:32.349Z","etag":null,"topics":["agentic","agentic-ai","deepseek","linux","linux-desktop","llm","xfce","zai"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/agiUnderground.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-01-24T21:56:10.000Z","updated_at":"2026-03-01T09:35:35.000Z","dependencies_parsed_at":"2025-08-30T02:18:21.648Z","dependency_job_id":"85de9ea4-c17d-4b8d-929b-10d8775b825f","html_url":"https://github.com/agiUnderground/useless-agent","commit_stats":null,"previous_names":["agiunderground/useless-agent"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/agiUnderground/useless-agent","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agiUnderground%2Fuseless-agent","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agiUnderground%2Fuseless-agent/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agiUnderground%2Fuseless-agent/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agiUnderground%2Fuseless-agent/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/agiUnderground","download_url":"https://codeload.github.com/agiUnderground/useless-agent/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agiUnderground%2Fuseless-agent/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30027014,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-03T00:31:48.536Z","status":"ssl_error","status_checked_at":"2026-03-03T00:30:56.176Z","response_time":60,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agentic","agentic-ai","deepseek","linux","linux-desktop","llm","xfce","zai"],"created_at":"2025-01-30T14:38:48.387Z","updated_at":"2026-03-03T00:31:49.092Z","avatar_url":"https://github.com/agiUnderground.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# useless-agent \n\n![](/assets/img/demo2.png)\n\n**What can this agent do?** Basically nothing, that’s why it is the useless-agent.  \n\n**Why is it interesting?**  \n\n* Uses text-only LLMs.  \n* Cheap: I spent about $4.57 playing with it for about 7 evenings.  \n* Single binary. *(almost, see todo list)*  \n* Easy to use: run the binary and copy the IP address.  \n* No telemetry, no bullshit.\n* IPv4 \u0026 IPv6(*should work, not tested yet)\n\n**:star: Would you like me to work more on this project? Please consider giving this repository a star!**  \n\n\u003e [!CAUTION]  \n\u003e * Only use this on a disposable virtual machine.  \n\u003e * It can, and most likely will, destroy your system.  \n\u003e * The LLM API provider has a realistic ability to inject malicious commands/actions/data into the ingested API responses.  \n\u003e * The video is not compressed. If you are connected to a virtual machine in the cloud, be aware of high internet traffic.  \n\u003e * The video stream and everything else, except the API queries, are not encrypted. If connecting to a remote machine, use an SSH tunnel with port forwarding.  \n\n\u003e [!NOTE]  \n\u003e It is super slow. Right now, speed is not a priority. If your only problem is speed, you have already won the agents game.  \n\nCurrently supported llm providers:\n* `DeepSeek`\n* `Z.AI`\n\nCurrently supported models:\n* `deepseek-chat`\n* `deepseek-reasoner`\n* `glm-5`\n* `glm-4.6`\n* `glm-4.5`\n* `glm-4.5-air`\n* `glm-4.5-flash`\n\n**Environment**: Only works on - `Linux + xfce + X11`.  \n\n# Changelog\n\n### v0.0.3\n* User-assist feature works.\n* Faster task cancellation.\n* Extract css and js from the html file.\n* Fixed routing of the line which connects chat and session window.\n* Fixed media buttons overlay resizing.\n* Tasks destined to the same session now queued.\n* Use more API of the environment where it's possible.\n* Break main.go into separate packages.\n* Other small fixes.\n\n### v0.0.2\n\n* Manage multiple sessions at once.\n* Fullscreen \u0026 maximize control elements for the video stream. Hotkeys F and M.\n* Added a button to the task card to reopen a session window.\n* MVP of the user-assist feature, only UI for now.\n* Smart scrolling for the tasks section.\n* Many small UI bugfixes and improvements.\n\n![](/assets/img/multi-session-feature.png)\n\u003cp align=\"center\"\u003eMulti-session\u003c/p\u003e\n\n![](/assets/img/user-assist-feature.png)\n\u003cp align=\"center\"\u003eUser-assist\u003c/p\u003e\n\n### v0.0.1\n\n* Added basic tasks management and status indication.\n* Hotkeys support.\n* UI update.\n* Video stream FPS selector.\n\n![](/assets/img/tasks-management.png)\n\n# Q\u0026A\n* Can I put something like `http://127.0.0.1:11434/v1` into `API_BASE_URL=''` and use a model that I run locally? - Yes.\n\n# Demos\n\n`Prompt`: Open a web browser and go to deepseek.com\n\nhttps://github.com/user-attachments/assets/6299f1b5-3c2e-493e-b67a-145487e14ffa\n\n`Prompt`: Very detailed prompt to create a ping pong tcp client and server(neovim)\n\nhttps://github.com/user-attachments/assets/370bdd7e-0955-4b1e-8e81-8ee3eb913e90\n\n\n\n### How to build:\n\n**The easiest way:**\n```bash\ndocker compose up --build\n```\n\nFor more information, see [DOCKER_README.md](DOCKER_README.md).\n\n\u003e [!WARNING]\n\u003e Docker is not a sufficient level of isolation and it is risky.\n\n**or manually:**\n* `git clone`\n* `cd useless-agent`\n* `go build`\n\n### How to prepare headless vm:\nScripts - \"assets/scripts\"\n```bash\nsudo apt update \u0026\u0026 sudo add-apt-repository ppa:alex-p/tesseract-ocr5 \u0026\u0026 sudo apt install -y \\\n  xfce4 xvfb tesseract-ocr-eng tesseract-ocr libtesseract5 libleptonica-dev libtesseract-dev\nsudo apt remove -y xfce4-screensaver\nsudo systemctl enable --now xvfb.service xfce4.service\n```\n\n### How to establish a secure tunnel between client and remote server:\n```bash\nssh -p 22 -fN -o IPQoS=ef USERNAME@REMOTE-HOST-PUBLIC-IP -L 127.0.0.1:8080:127.0.0.1:8080\n```\n\n### How to use:\n`copy executable to the target machine`\n\n`start executable:`\n```bash\n./useless-agent --provider=deepseek --base-url=\"https://api.deepseek.com/v1\" --key=YOUR-API-KEY --model='deepseek-chat' --display=:1 --ip=127.0.0.1 --port=8080\n./useless-agent --provider=zai --base-url=\"https://api.z.ai/api/paas/v4\" --key=\"YOUR-API-KEY\" --model='glm-4.5-air' --display=:1 --ip=127.0.0.1 --port=8080\n```\n`On client machine open main.html in the browser.`\n\n`Put target machine IP into the field \"IP Address\".`\n\n`Click \"Connect\".`\n\n`Give it some task, for example \"Open web browser\", put that prompt into the LLM Chat and press \"Send\".`\n\n\u003e [!TIP]  \n\u003e Like to burn money? Try more capable LLMs; using DeepSeek R1 instead of v3 would probably make the program more capable of doing nothing.\n\n### Todo list:  \n- [ ] Build a single fully static binary.  \n- [X] Add stats about burned tokens.\n- [ ] Allow LLM to spawn local 'thoughts', which would do/monitor something and then allow them to interrupt the main LOOP and to inject its results into the thinking loop.\n- [ ] Build a unified concept space for models that are capable of ingesting more data.\n- [ ] Pause task execution.\n- [X] Allow intervention in the execution process and provide guidance/additional instructions.\n\n**Problems \u0026 Ideas:**  \n* LLMs' context window/input size is so limiting; I want to shuffle in 100M million tokens at each iteration.  \n* How to do reliable OCR? Don’t do it at all. The idea was to find a single point where Linux renders fonts for the whole system and intercept it, to set something like an eBPF hook and get all text for free. `Turns out there is no single point of font rendering in Linux!` Each X11 client app is allowed to render fonts itself. Nice.  \n* How hard could it be to write a single function to recognize windows? They have unified patterns, right? `Wrong. Each window is allowed to draw its own header however they like.` I’m looking at you, Firefox. Nice.  \n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fagiunderground%2Fuseless-agent","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fagiunderground%2Fuseless-agent","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fagiunderground%2Fuseless-agent/lists"}