{"id":30444467,"url":"https://github.com/synthetic-lab/octofriend","last_synced_at":"2025-08-23T10:05:03.781Z","repository":{"id":284425426,"uuid":"954908083","full_name":"synthetic-lab/octofriend","owner":"synthetic-lab","description":"An open-source coding helper. Very friendly!","archived":false,"fork":false,"pushed_at":"2025-08-19T11:31:45.000Z","size":4144,"stargazers_count":458,"open_issues_count":10,"forks_count":36,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-08-19T11:35:00.593Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/synthetic-lab.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"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}},"created_at":"2025-03-25T19:57:47.000Z","updated_at":"2025-08-19T11:31:48.000Z","dependencies_parsed_at":"2025-07-11T22:17:01.438Z","dependency_job_id":"ab60dad7-3c7b-4565-b197-af26616a7be1","html_url":"https://github.com/synthetic-lab/octofriend","commit_stats":null,"previous_names":["reissbaker/octofriend","synthetic-lab/octofriend"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/synthetic-lab/octofriend","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/synthetic-lab%2Foctofriend","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/synthetic-lab%2Foctofriend/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/synthetic-lab%2Foctofriend/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/synthetic-lab%2Foctofriend/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/synthetic-lab","download_url":"https://codeload.github.com/synthetic-lab/octofriend/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/synthetic-lab%2Foctofriend/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":271746516,"owners_count":24813568,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-23T02:00:09.327Z","response_time":69,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":[],"created_at":"2025-08-23T10:02:20.423Z","updated_at":"2025-08-23T10:05:03.768Z","avatar_url":"https://github.com/synthetic-lab.png","language":"TypeScript","funding_links":[],"categories":["Related Projects","TypeScript","Alternatives to Claude Code","others"],"sub_categories":[],"readme":"Octo is a small, helpful, zero-telemetry, cephalopod-flavored coding assistant.\nOcto is your friend.\n\n## Get Started\n\n```bash\nnpm install --global --omit=dev octofriend\n```\n\nAnd then:\n\n```bash\noctofriend\n# or, for short:\nocto\n```\n\n![octofriend](https://raw.githubusercontent.com/synthetic-lab/octofriend/main/octofriend.png)\n\n## About\n\nOcto is a small, helpful, cephalopod-flavored coding assistant that works with\nany OpenAI-compatible or Anthropic-compatible LLM API, and allows you to switch\nmodels at will mid-conversation when a particular model gets stuck. Octo can\noptionally use (and we recommend using) ML models we custom-trained and\nopen-sourced ([1](https://huggingface.co/syntheticlab/diff-apply),\n[2](https://huggingface.co/syntheticlab/fix-json)) to automatically handle tool\ncall and code edit failures from the main coding models you're working with:\nthe autofix models work with any coding LLM. Octo wants to help you because\nOcto is your friend.\n\nOcto works great with GPT-5, Claude 4, GLM-4.5, and Kimi K2 (although you can\nuse it with pretty much anything!). Correctly handling multi-turn responses,\nespecially with thinking models like GPT-5 and Claude 4 (whose content may\neven be encrypted), can be tricky. Octo carefully manages thinking tokens to\nensure it's always as smart as it can be. We think it's the best multi-LLM tool\nout there at managing thinking tokens, and you'll feel how much smarter it is.\n\nOcto has zero telemetry. Using Octo with a privacy-focused LLM provider (may we\nselfishly recommend [Synthetic](https://synthetic.new)?) means your code stays\nyours. But you can also use it with any OpenAI-compatible API provider, with\nAnthropic, or with local LLMs you run on your own machine.\n\nOcto has helped write some of its own source code, but the codebase is\nhuman-first: Octo is meant to be a friendly little helper rather than a\ncompletely hands-free author, and that's how I use it. But if you want to live\ndangerously, you can always run `octofriend --unchained`, and skip all tool and\nedit confirmations.\n\n## Demo\n[![Octo asciicast](https://raw.githubusercontent.com/synthetic-lab/octofriend/main/octo-asciicast.svg)](https://asciinema.org/a/728456)\n\n## Sandboxing Octo\n\nOcto has built-in Docker support, and can attach to any Docker container\nwithout needing special configuration or editing the image or container. To\nmake Octo run inside an *existing* container you have running — for example, if\nyou already have a Docker Compose setup — run `octo docker connect\nyour-container-name`.\n\nTo have Octo launch a Docker image and shut it down when Octo quits, you can\nrun:\n\n```bash\n# Make sure to add the -- before the docker run args!\nocto docker run -- ordinary-docker-run-args\n```\n\nFor example, to launch Octo inside an Alpine Linux container:\n\n```bash\nocto docker run -- -d -i -t alpine /bin/sh\n```\n\nAll of Octo shell commands and filesystem edits and reads will happen inside\nthe container. However, Octo will continue to use any MCP servers you have\ndefined in your config via your host machine (since the MCP servers are\npresumably running on your machine, not inside the container), and will make\nHTTP requests from your machine as well if it uses the built-in `fetch` tool,\nso that you can use arbitrary containers that may not have `wget` or `curl`\ninstalled.\n\n## Rules\n\nOcto will look for instruction files named like so:\n\n- `OCTO.md`\n- `CLAUDE.md`\n- `AGENTS.md`\n\nOcto uses the *first* one of those it finds: so if you want to have different\ninstructions for Octo than for Claude, just have an `OCTO.md` and a\n`CLAUDE.md`, and Octo will ignore your `CLAUDE.md`.\n\nOcto will search the current directory for rules, and every parent directory,\nup until (inclusive of) your home directory. All rule files will be merged: so\nif you want project-specific rules as well as general rules to apply\neverywhere, you can add an `OCTO.md` to your project, as well as a global\n`OCTO.md` in your home directory.\n\nIf you don't want to clutter your home directory, you can also add a global\nrules file in `~/.config/octofriend/OCTO.md`.\n\n## Connecting Octo to MCP servers\n\nOcto can do a lot out of the box — pretty much anything is possible with enough\nBash — but if you want access to rich data from an MCP server, it'll help Octo\nout a lot to just provide the MCP server directly instead of trying to contort\nits tentacles into crafting the right Bash-isms. After you run `octofriend` for\nthe first time, you'll end up with a config file in\n`~/.config/octofriend/octofriend.json5`. To hook Octo up to your favorite MCP\nserver, add the following to the config file:\n\n```json5\nmcpServers: {\n  serverName: {\n    command: \"command-string\",\n    arguments: [\n      \"arguments\",\n      \"to\",\n      \"pass\",\n    ],\n  },\n},\n```\n\nFor example, to plug Octo into your Linear workspace:\n\n```json5\nmcpServers: {\n  linear: {\n    command: \"npx\",\n    arguments: [ \"-y\", \"mcp-remote\", \"https://mcp.linear.app/sse\" ],\n  },\n},\n```\n\n## Using Octo with local LLMs\n\nIf you're a relatively advanced user, you might want to use Octo with local\nLLMs. Assuming you already have a local LLM API server set up like ollama or\nllama.cpp, using Octo with it is super easy. When adding a model, make sure to\nselect `Add a custom model...`. Then it'll prompt you for your API base URL,\nwhich is probably something like: `http://localhost:3000`, or whatever port\nyou're running your local LLM server on. After that it'll prompt you for an\nenvironment variable to use as a credential; just use any non-empty environment\nvariable and it should work (since most local LLM server ignore credentials\nanyway).\n\nYou can also edit the Octofriend config directly in\n`~/.config/octofriend/octofriend.json5`. Just add the following to your list of\nmodels:\n\n```json5\n{\n  nickname: \"The string to show in the UI for your model name\",\n  baseUrl: \"http://localhost:SOME_PORT\",\n  apiEnvVar: \"any non-empty env var\",\n  model: \"The model string used by the API server, e.g. openai/gpt-oss-20b\",\n}\n```\n\n## Debugging\n\nBy default, Octo tries to present a pretty clean UI. If you want to see\nunderlying error messages from APIs or tool calls, run Octo with the\n`OCTO_VERBOSE` environment variable set to any truthy string; for example:\n\n```bash\nOCTO_VERBOSE=1 octofriend\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsynthetic-lab%2Foctofriend","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsynthetic-lab%2Foctofriend","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsynthetic-lab%2Foctofriend/lists"}