{"id":49394724,"url":"https://github.com/ashref-dev/fi.ashref.tn","last_synced_at":"2026-04-28T15:02:56.351Z","repository":{"id":337252088,"uuid":"1152858810","full_name":"Ashref-dev/fi.ashref.tn","owner":"Ashref-dev","description":null,"archived":false,"fork":false,"pushed_at":"2026-03-20T04:54:39.000Z","size":393,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-20T21:15:18.302Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"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/Ashref-dev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","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":"2026-02-08T14:49:37.000Z","updated_at":"2026-03-20T04:54:43.000Z","dependencies_parsed_at":"2026-02-08T21:02:01.835Z","dependency_job_id":null,"html_url":"https://github.com/Ashref-dev/fi.ashref.tn","commit_stats":null,"previous_names":["ashref-dev/fi.ashref.tn"],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/Ashref-dev/fi.ashref.tn","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ashref-dev%2Ffi.ashref.tn","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ashref-dev%2Ffi.ashref.tn/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ashref-dev%2Ffi.ashref.tn/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ashref-dev%2Ffi.ashref.tn/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Ashref-dev","download_url":"https://codeload.github.com/Ashref-dev/fi.ashref.tn/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ashref-dev%2Ffi.ashref.tn/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32385943,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-28T14:34:11.604Z","status":"ssl_error","status_checked_at":"2026-04-28T14:32:37.009Z","response_time":56,"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":[],"created_at":"2026-04-28T15:02:51.047Z","updated_at":"2026-04-28T15:02:56.345Z","avatar_url":"https://github.com/Ashref-dev.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# fi-cli\n\nfi-cli is a terminal-native agent orchestrator for repository Q\u0026A and local branch review. It prioritizes local evidence (`grep` + `list_tree` + repo context), can optionally use web search for Q\u0026A, and is read-only by default.\n\nThis README reflects current behavior validated by integration/unit tests in this repository.\n\n## Install\n\n1. Build:\n   ```bash\n   go build -o fi-cli ./cmd/fi-cli\n   ```\n2. Install into PATH:\n   ```bash\n   install -m 0755 fi-cli ~/.local/bin/fi-cli\n   export PATH=\"$HOME/.local/bin:$PATH\"\n   ```\n3. Optional shorthand alias:\n   ```bash\n   alias fic='fi-cli'\n   ```\n4. Initialize config:\n   ```bash\n   fi-cli init\n   ```\n5. Edit the generated config file and set `api_key`.\n6. Run:\n   ```bash\n   fi-cli \"what's the tech stack here?\"\n   ```\n7. Inspect runtime policy/settings any time:\n   ```bash\n   fi-cli about\n   fi-cli policy check\n   ```\n\n## First-Run Onboarding\n\nIf no API key is configured, fi-cli prints onboarding instructions and exits with code `2`.\n\n## Configuration\n\nConfig file locations:\n- `~/.config/fi.ashref.tn/config.yaml`\n- `~/.config/fi.ashref.tn/config.json`\n- `~/Library/Application Support/fi.ashref.tn/config.yaml` (macOS)\n\nExample config:\n\n```yaml\napi_key: \"your_openrouter_key\"\nmodel: openrouter/pony-alpha\nfallback_models:\n  - openrouter/anthropic/claude-3.5-sonnet\n  - openrouter/openai/gpt-4o-mini\nopenrouter_base_url: \"https://openrouter.ai/api/v1\"\nresponse_mode: quick\nshow_header: false\nshow_tools: true\nno_plan: true\nllm_retry_max_attempts: 2\nllm_retry_initial_backoff: 300ms\nllm_retry_max_backoff: 2s\nllm_circuit_failure_threshold: 5\nllm_circuit_window: 30s\nllm_circuit_open_duration: 15s\ntool_parallelism: 4\ntool_timeout_seconds: 10\nreview_max_files: 20\nreview_max_findings: 25\nreview_instructions_file: \".fi/review.md\"\nreview_path_rules_file: \".fi/review-paths.yaml\"\ntool_limits:\n  grep_max_calls: 30\n  shell_max_calls: 30\n  web_max_calls: 30\n# shell_allowlist:\n#   - git status\n#   - git log\n```\n\nEnvironment variables:\n- `FICLI_API_KEY` (preferred; fallback: `OPENROUTER_API_KEY`, `OPENAI_API_KEY`)\n- `FICLI_MODEL`, `FICLI_FALLBACK_MODELS` (comma-separated), `FICLI_OPENROUTER_BASE_URL`\n- `FICLI_TIMEOUT_SECONDS`, `FICLI_MAX_STEPS`\n- `FICLI_TOOL_PARALLELISM`, `FICLI_TOOL_TIMEOUT_SECONDS`\n- `FICLI_LLM_RETRY_MAX_ATTEMPTS`, `FICLI_LLM_RETRY_INITIAL_BACKOFF`, `FICLI_LLM_RETRY_MAX_BACKOFF`\n- `FICLI_LLM_CIRCUIT_FAILURE_THRESHOLD`, `FICLI_LLM_CIRCUIT_WINDOW`, `FICLI_LLM_CIRCUIT_OPEN_DURATION`\n- `FICLI_REVIEW_MAX_FILES`, `FICLI_REVIEW_MAX_FINDINGS`\n- `FICLI_REVIEW_INSTRUCTIONS_FILE`, `FICLI_REVIEW_PATH_RULES_FILE`\n- `FICLI_RESPONSE_MODE` (`quick`, `operator`, `explain`)\n- `FICLI_SHOW_HEADER`, `FICLI_SHOW_TOOLS`, `FICLI_NO_TOOLS`, `FICLI_NO_PLAN`\n- `FICLI_TIMINGS` (print stage timing diagnostics)\n- `FICLI_SHELL_ALLOWLIST`, `FICLI_LOG_FILE`, `FICLI_PERSIST_RUNS`\n- `FICLI_HISTORY_LINES`, `FICLI_NO_HISTORY`\n- `EXA_API_KEY` (optional; enables `exa_search`)\n\n## Runtime UX\n\n- Planning is opt-in: default behavior is execute directly without a plan.\n- Use `--plan` to request planning first.\n- Every run starts with an automatic `list_tree` snapshot (`path=\".\"`, `max_depth=2`) so the model sees top-level project layout before answering.\n- After structure snapshot, the model is guided to run focused `grep` evidence before final output.\n- Text mode streams model output and shows a transient `thinking` spinner while waiting.\n- Spinner resumes under plan/tool lines and stops on first model token or run completion.\n- `--timings` prints per-stage timing diagnostics and the slowest stage.\n- Tool calls in a single model step run in parallel only when every call is read-only and allowlisted (`grep`, `exa_search`, `list_tree`).\n- Tool result messages are always fed back to the model in the original call order (deterministic behavior).\n- LLM calls use retry/backoff, a per-run circuit breaker, and optional fallback model chain.\n- Review mode builds diff context with dedicated read-only Git tools (`git_refs`, `git_merge_base`, `git_changed_files`, `git_diff_hunks`, `git_file_at_ref`, `git_blame_lines`, `git_log_range`) instead of model-exposed shell access.\n\n## Safety Policy\n\nDefault mode is `read-only` (shell disabled).\n\nUse:\n```bash\nfi-cli policy check\nfi-cli policy test \"git status -sb\"\n```\n\nModes:\n- `read-only`: `grep` + `list_tree` + repo context only (shell disabled)\n- `allowlist`: shell enabled only for configured command prefixes\n- `unsafe`: enabled explicitly with `--unsafe-shell`\n\nTool call budgets (default):\n- `grep`: 30 calls/run\n- `shell`: 30 calls/run\n- `exa_search`: 30 calls/run\n\n## Usage\n\n```bash\nfi-cli \"where is auth implemented?\"\nfi-cli --mode operator \"how do I run this project?\"\nfi-cli --plan --show-header \"summarize architecture\"\nfi-cli --timings \"where is auth implemented?\"\nfi-cli \"show me the folder structure\"\nfi-cli --fallback-model openrouter/openai/gpt-4o-mini \"analyze this repository\"\nfi-cli --no-tools \"quick summary\"\nfi-cli --shell-allow \"git status\" \"show git status\"\nfi-cli --shell-allow \"ls\" --shell-allow \"ls -la\" \"inspect current repo context\"\nfi-cli review --base main\nfi-cli review --base dev --head HEAD --timings\nfi-cli review --base main --working-tree --json\nfi-cli\n```\n\nInput tips (zsh/macOS):\n- You can run `fi-cli` with no args and type at `question\u003e`.\n- If your inline question contains apostrophes (`'`), prefer double quotes around the full question.\n- `quote\u003e` in zsh means your shell is waiting for a closing quote before fi-cli starts.\n\nDefault output is concise:\n```text\ntool: grep ok (12ms, 8 lines, 644 bytes)\nfi: \u003canswer\u003e\n```\n\nStructure discovery output uses `list_tree`:\n```text\ntool: list_tree ok (6ms, 42 lines, 2103 bytes)\nfi: \u003canswer\u003e\n```\n\nTiming output example:\n```text\ntimings:\n  question_resolution_input: 1ms\n  config_load: 2ms\n  repo_root_resolution: 1ms\n  repo_context_build: 7ms\n  history_load: 1ms\n  planning: 0ms\n  first_model_response_wait: 1834ms\n  tool_execution_total: 28ms\n  first_answer_token_latency: 1836ms\n  total_run_duration: 2042ms\n  slowest_stage: first_model_response_wait (1834ms)\n```\n\n## Review Mode\n\n`fi-cli review` is a local-only branch review workflow. It keeps the root Q\u0026A mode unchanged and adds a separate diff-scoped reviewer for merge readiness.\n\nBehavior:\n- `head` defaults to `HEAD`\n- `base` auto-detects in this order: `origin/HEAD`, `origin/main`, `main`, `origin/master`, `master`\n- review scope is `merge-base(base, head)...head`\n- working tree changes are excluded by default; add `--working-tree` to include staged and unstaged local edits\n- output is human-readable text by default or JSON with `--json`\n- exit code `3` means review completed and found at least one blocker\n\nReview files:\n- `.fi/review.md`: repository-wide review instructions\n- `.fi/review-paths.yaml`: optional path-specific rules\n- path rules use Go `path.Match` semantics, so write explicit segment globs such as `internal/*/*.go`\n\nExample `.fi/review-paths.yaml`:\n\n```yaml\nrules:\n  - glob: \"internal/*/*.go\"\n    instructions: \"Focus on correctness, concurrency, and missing tests.\"\n  - glob: \"cmd/*/*.go\"\n    instructions: \"Check CLI behavior, flags, and backwards compatibility.\"\n```\n\nReview output includes:\n- score out of 5\n- merge recommendation\n- blockers\n- findings grouped by severity\n- strengths\n- reviewed and skipped file coverage\n- `stage_timings_ms` in JSON output\n\nReview timing output example:\n\n```text\ntimings:\n  ref_resolution: 1ms\n  merge_base_resolution: 4ms\n  changed_files_scan: 8ms\n  diff_context_build: 6ms\n  triage: 0ms\n  deep_review: 18ms\n  model_wait_total: 3ms\n  aggregation: 0ms\n  total_run_duration: 39ms\n  slowest_stage: deep_review (18ms)\n```\n\nShell context tip:\n- In allowlist mode, add `ls` / `ls -la` to `shell_allowlist` if you want the agent to quickly inspect top-level context before deeper commands.\n\nHistory context:\n- By default, fi-cli includes recent shell history lines in model context (`FICLI_HISTORY_LINES`, disable with `--no-history` / `FICLI_NO_HISTORY`).\n\n## License\n\nMIT. See `LICENSE`.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fashref-dev%2Ffi.ashref.tn","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fashref-dev%2Ffi.ashref.tn","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fashref-dev%2Ffi.ashref.tn/lists"}